---
title: "API response format"
slug: "api-response-format"
updated: 2026-08-10T06:00:06Z
published: 2026-08-10T06:00:06Z
canonical: "apidocs.document360.com/api-response-format"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.document360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API response format

The Document360 v3 API returns JSON responses with a consistent structure. Always check the `success` flag before reading `data`.

## Success response

Single-resource responses use an `ApiResponse` envelope:

```
{
  "success": true,
  "request_id": "req_abc123def456",
  "data": { },
  "errors": [],
  "warnings": []
}
```

| Field | Description |
| --- | --- |
| `success` | `true` when the request succeeded. |
| `request_id` | Unique identifier for the request — quote it in support tickets. |
| `data` | The response payload; an object, or an array for list endpoints. |
| `errors` | Array of errors, empty on success. |
| `warnings` | Array of non-fatal warnings. |

## Paginated response

List endpoints add a `pagination` block:

```
{
  "success": true,
  "request_id": "req_abc123def456",
  "data": [],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "total_count": 42,
    "has_more": true,
    "next_cursor": null
  }
}
```

`total_count` is included only when `include_total_count=true` is passed. For cursor-based paging, use `next_cursor` as the `cursor` parameter of the next request.

## Error response

Errors are returned as RFC 7807 `problem+json` with the content type `application/problem+json`. Each error carries a machine-readable `code` and, where relevant, the `field` that failed validation.

```
{
  "type": "https://apidocs.document360.io/apidocs/errors/validation-error",
  "title": "Validation failed.",
  "status": 422,
  "detail": "One or more fields failed validation.",
  "instance": "/v3/projects/{project_id}/articles",
  "trace_id": "req_abc123def456",
  "errors": [
    { "code": "VALIDATION_ERROR", "message": "The field is required.", "field": "title" }
  ]
}
```

| Field | Description |
| --- | --- |
| `type` | A URI identifying the error category. |
| `title` | Short, human-readable summary. |
| `status` | The HTTP status code. |
| `detail` | Human-readable explanation of this occurrence. |
| `instance` | The request path that produced the error. |
| `trace_id` | Correlates the error with server-side logs. |
| `errors[]` | Array of errors, each with `code`, `message`, and optional `field` and `details`. |
| `warnings[]` | Array of non-fatal warnings. |
| `upgrade_url` | Present only on a `403 PREMIUM_FEATURE_NOT_IN_LICENSE` response, when configured. |

## Error codes

The `code` field uses a fixed set of values:

| Code | Meaning |
| --- | --- |
| `BAD_REQUEST` | Malformed request. |
| `UNAUTHORIZED` | Missing or invalid API key. |
| `FORBIDDEN` | Authenticated but not permitted — role, content ACL, or scope. |
| `RESOURCE_NOT_FOUND` | The resource does not exist. |
| `CONFLICT` | Conflicts with the current state, for example a duplicate. |
| `VALIDATION_ERROR` | One or more fields failed validation. |
| `UNRECOGNIZED_FIELD` | The request body contains an unknown field. |
| `UNRECOGNIZED_FIELDS` | The request body contains multiple unknown fields. |
| `OPERATION_FAILED` | The operation could not be completed. |
| `FEATURE_NOT_IN_LICENSE` | The feature is not available in your current plan. |
| `PREMIUM_FEATURE_NOT_IN_LICENSE` | The endpoint is part of the premium API add-on, which is not enabled for your project. |
| `LICENSE_LIMIT_EXCEEDED` | Your plan's limit, for example team account or reader seats, is exhausted. |
| `TOO_MANY_REQUESTS` | Rate limit exceeded. |
| `INTERNAL_SERVER_ERROR` | Unexpected server error. |

Tip

Always check `success` first. Use the `code` field for programmatic handling rather than parsing human-readable messages.