Errors and idempotency - Doconda

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

{
  "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.

⌘I