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

# Errors and idempotency

> RFC 9457 errors and safe retries.

Errors are `application/problem+json` with a stable `code`:

```json theme={null}
{
  "type": "https://docs.doconda.com/errors/input_invalid",
  "title": "The request is not valid.",
  "status": 422,
  "code": "input_invalid",
  "request_id": "req_…",
  "errors": [{ "path": "/style/font_size", "message": "must be <= 16" }]
}
```

| Code | HTTP | What to do |
| - | - | - |
| `input_invalid` | 422 | Fix the request; `errors[].path` points to the field and `message` says what's wrong. |
| `unauthorized` | 401 | Send `Authorization: Bearer ak_…` with a valid key. |
| `insufficient_balance` | 402 | Not enough balance left for this document: top up in the dashboard (or turn on auto top-up). |
| `session_required` | 403 | That route is dashboard-only; it can't be used with an API key. |
| `region_mismatch` | 401 | The key's project is in another region: use that region's URL. |
| `link_expired` | 410 | The artifact link has expired: get another one with `GET /documents/{id}/outputs`. |
| `rate_limited` | 429 | More than 120 documents per minute in the organization, or too many reads or writes on an artifact. Wait a moment and retry. |
| `not_an_artifact` | 409 | Only documents with `format: "artifact"` store data. |
| `record_too_large` | 413 | A `doconda.db` record is over 16 KB. |
| `too_many_records` | 409 | The artifact already has 5,000 records. |
| `not_found` | 404 | The document or file doesn't exist (or belongs to another organization). |
| `file_rejected` | 422 | The file isn't valid: unsupported type or with macros (`.docm`, `.pptm`, `.xlsm`). |
| `file_too_large` | 413 | Files can be up to 20 MB. |
| `report_not_ready` | 409 | The report exists once the document finishes: wait or follow its events. |
| `content_deleted` | 410 | You asked for `store: false` and the 15 minutes have passed: the content has been deleted. |
| `project_does_not_store` | 422 | The project doesn't store content: an artifact can only be `artifact.storage: "local"`. |
| `artifact_is_local` | 409 | That artifact stores its data in each visitor's browser: Doconda doesn't have it. |
| `events_expired` | 410 | Events are kept for 7 days: read the document with `GET /documents/{id}`. |
| `idempotency_key_reused` | 422 | You used the same `Idempotency-Key` with a different request. |
| `idempotency_request_in_progress` | 409 | The first request with that key hasn't finished yet: retry in a few seconds. |
| `feature_unavailable` | 501 | AI is not enabled in this deployment (affects `prompt`, editing and text style). |
| `internal_error` | 500 | Our fault. Retry; if it persists, write to us with the `request_id`. |

## When a document fails

If the problem shows up during processing, the request was already accepted: the document ends with `status: "failed"` and `error.code` explains why. You are not charged.

| `error.code` | What happened |
| - | - |
| `content_empty` | The content has nothing to show (headings, text, lists or tables). |
| `file_rejected` | When opening your file we found something we don't process (macros, abnormal structure, disallowed XML, a password-protected PDF). The message says what. |
| `docx_invalid` | The file is not a valid Word file. |
| `file_not_found` | The file was deleted before it was processed. |
| `document_too_long` | The document is too long to edit (about 50 pages). |
| `format_unclear` | You didn't set `format` and your `prompt` doesn't make clear whether you want a Word file, a PDF, a PowerPoint, an Excel file or an artifact: say it in `format`. |
| `edit_not_understood` | We couldn't turn what you asked for into concrete changes: say it more precisely. |
| `edit_not_applied` | None of the requested changes could be applied to that document; the report says why. |
| `source_unreadable` | We couldn't read one of the files in `sources`. |
| `generation_blocked` | The model declined to write that document: rephrase the request. |
| `page_too_large` | The artifact page exceeds the maximum size. |
| `processing_failed` | We couldn't process it after several attempts. Try again later. |

## Idempotency

Send `Idempotency-Key` in `POST /documents`. If you repeat the request with the same key and the same body (within 24 h, in the same project), you get the same document without creating another one or being charged twice. With a different body, `422 idempotency_key_reused`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.