Errors
Every error has the same shape. Branch on code: it is stable, while message is for people and may change.
422 Unprocessable Entity
{ "error": { "type": "invalid_request", "code": "answers_invalid", "message": "qst_01JB8ZK9P4MC0H2N4R6T8V0X2B: type (expected number).", "fields": [ { "field": "qst_01JB8ZK9P4MC0H2N4R6T8V0X2B", "issue": "type", "expected": "number" } ], "request_id": "req_01JB8ZK4QWX2M7R9T3V5N8P6CD" }}- type groups codes by HTTP status (below).
- fields lists each bad field with an issue: missing, type, invalid, unknown_field or not_asked.
- retryable: true means the same request can succeed later.
- request_id is also in the Request-Id header. Quote it when you contact support.
Types
| Status | Type | Meaning |
|---|---|---|
| 400 | invalid_request | The request could not be read. |
| 401 | authentication_error | No key, or a key we do not know. |
| 404 | not_found | The thing you asked for does not exist for this key. |
| 409 | conflict | The request clashes with the current state. |
| 410 | gone | It existed, but expired and was deleted. |
| 422 | invalid_request | The request was read but a value is wrong. |
| 429 | rate_limit_error | Too many requests for this key. |
| 500, 503 | api_error | Our side failed. Safe to retry with the same Idempotency-Key. |
Common to every endpoint
| Status | Code | What to do |
|---|---|---|
| 400 | body_invalid | The body isn't valid JSON for this endpoint; message says where it broke. |
| 400 | body_too_large | Bodies are limited to 1 MB. |
| 400 | idempotency_key_invalid | Keys are at most 255 characters. |
| 401 | key_missing | Send Authorization: Bearer dg_test_… (or a dgt_… access token). |
| 401 | key_invalid | The key or access token is unknown, revoked or expired. Check it and its environment. |
| 401 | secret_key_in_browser | The request came from a browser (it has an Origin header). Call the API from your server; never ship a key to a browser. |
| 409 | idempotency_key_reused | The key was used with a different body. Use a new key for a new request. |
| 409 | idempotency_request_in_progress | The first request with this key is still running. Retry shortly. |
| 429 | rate_limited | Wait Retry-After seconds |
| 500 | internal_error | Our fault. Retry with the same Idempotency-Key; quote request_id to support. |
Endpoint codes
| Status | Code | What to do |
|---|---|---|
| 401 | launch_code_invalid | The code is unknown, already used, expired (5 minutes), or its key was revoked. Open the link from the portal again. |
| 404 | document_not_found | Check the ID and that it belongs to your organisation. |
| 404 | file_not_found | The link is not valid. Take the URL from the document again. |
| 404 | session_not_found | Check the ID, and that Docgen-Subject is the subject the session was created for. |
| 409 | session_closed | The session was closed and takes no more messages. Start a new one. |
| 409 | session_not_ready | The session is still finding the form or asking questions; pending_question is what is left. |
| 409 | turn_in_progress | Another message to this session is being handled. Retry when it returns. |
| 410 | document_expired | The files were deleted at expires_at. Generate it again. |
| 410 | file_expired | The link passed its expires_at and the file was deleted. |
| 410 | session_deleted | The session was deleted with its conversation and answers. Start a new one. |
| 422 | answer_invalid | error.fields says what the question expects; for a form question, one of its option values. |
| 422 | format_unavailable | DOCX is not available yet; ask for pdf or html. A form filed on its official PDF (a deed, for example) comes only as pdf. |
| 422 | jurisdiction_invalid | Use a state code such as US-FL. |
| 422 | mode_unavailable | A form filed on its official PDF comes only in advanced mode, which is its default. The session's document.generate action lists the modes and formats a form offers. |
| 422 | parameter_invalid | error.fields names the bad parameter (message, settings, lifetime_seconds, metadata). |
| 422 | parameter_missing | Send text, answer, or both. |
| 422 | question_invalid | Answer pending_question.id, or a question already answered. |
| 422 | subject_required | Send Docgen-Subject, set from your own login (never from what the browser sent). |
| 503 | provider_unavailable | Finding a form by conversation needs a model; live keys get this until one is configured. |