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

# Abacus Docs API Error Codes, HTTP Statuses and Handling

> A complete reference of Abacus Docs API error codes, HTTP statuses, and guidance for resolving the most common integration issues.

`/api/v2/` is Django REST Framework. Error bodies are usually `{"detail": "…"}` or a field-keyed validation object. There is **no** `{ data, error, meta.request_id }` wrapper and no `doc_…` ids.

## Statuses you will see

| Status                     | When                                                                                                                             |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **400**                    | Malformed body, illegal state (for example a no-schema batch cannot take a default version)                                      |
| **401**                    | No usable credential                                                                                                             |
| **403**                    | You can see the row (or you authenticated) but this verb is not allowed. Also: API key on a personal route; ingest without Auth0 |
| **404**                    | Unknown id, **or** another organization's id. The API does not confirm foreign rows                                              |
| **409**                    | Conflict: chat turn already running, document still processing when you try to move it, ingest claim lost                        |
| **413** / upload rejection | File larger than **64 MB**                                                                                                       |
| **422**                    | Schema failed a hard Lynx contract on publish (field id, field cap, table with no columns)                                       |
| **426**                    | Ingest agent below the minimum version                                                                                           |
| **429**                    | Only if a gateway in front of the app rate-limits. Do not assume `X-RateLimit-*` headers                                         |
| **503**                    | Transient dependency (for example a completion callback asking you to retry)                                                     |

<Note>
  **404, not 403**, on a foreign or missing id is intentional. Do not treat 404 as "delete and recreate" without checking you have the right organization and id.
</Note>

## Validation

Serializer errors look like:

```json theme={null}
{
  "page_size": ["Ensure this value is less than or equal to 100."]
}
```

or a single `detail` string. Branch on the HTTP status first, then on field names if you need to highlight a form field.

## Retries

Retry **503** and network failures with backoff. Do **not** blindly retry **POST**s that start billable work (upload, reprocess, chat turn, ingest process) — a second call can charge again or create a second turn. Idempotent GETs and the ingest upload register (deduped on org + sha256) are safe to repeat.

## Uploads

Accepted library/chat uploads today: **PDF** and images (`.jpg`, `.jpeg`, `.png`, `.webp`, `.heic`, `.tiff`, `.tif`). **20** files per single upload, **1,024** per batch, **64 MB** per file. Digital formats (docx, xlsx, …) are not accepted until that flag is on.