Errors and retries

Every error has a stable code. Decide what to do from the code and the status; show your user a message of your own.

What to retry

• 429 rate_limited: wait Retry-After seconds. See Rate limits.
• 409 idempotency_request_in_progress: retry shortly with the same key.
• 500, 503 and network errors: retry with exponential backoff and the same Idempotency-Key.
• Anything with retryable: true.

What to fix

• 400, 422: the request is wrong. error.fields names each bad field; in a session, show it next to the question.
• 401: the key. See Authentication.
• 404: wrong ID, an ID from another organisation, or a session called with a different Docgen-Subject than it was created with (Subjects).
• 409: the object's state doesn't allow this: a session not yet ready to generate (session_not_ready), a closed one (session_closed), or a turn still running (turn_in_progress, retry when it returns).
• 410: it expired or was deleted. Start again; see Data lifetime.

The full list is in the error reference, and each endpoint lists its own.

Failed documents and turns

A document is a job, so it can fail after 202: status becomes failed with the reason in error, and the stream ends with document.failed. In a session, a model failure fails the turn: the reply has status: "failed" and an error, the session is unchanged, and you send the message again. A failure is never reported as completed or succeeded.