Skip to main content
Every error response from the API raises a DocondaError. The SDK retries network failures, 429 and 5xx on its own when sending the request twice is safe; everything else reaches your code at once. This page covers reading the error, what is retried, and how to never create the same document twice.

Read the error

Decide with code, never with the message: the text changes with the language and may be reworded. When the response has no body, code is http_error. For every code, see errors.

Failed documents aren’t exceptions

The API accepts a request before the document is made. If making it fails, create returns the document with status: "failed" and error.code (for example format_unclear); a canceled one comes back with status: "canceled". Neither is charged.
See when a document fails for every error.code.

Retries

The SDK retries network errors, 429 and 5xx up to maxRetries times (Python: max_retries, default 2), only for requests that are safe to send twice: reads, and requests that carry an Idempotency-Key (creating and canceling a document). A conversion, an upload, a hand-save (updateFile) and a new webhook endpoint go out once, so a lost answer never converts, saves or registers twice. Other 4xx errors are never retried: the same request would fail the same way. Before each retry it waits the seconds in Retry-After when the API sends it, otherwise 0.5 s and then 1 s. Every 429 from the per-minute limits carries Retry-After: the seconds until the next minute. wait() and create() also reconnect to the document’s event stream, up to 5 times in a row, if the connection drops.

Never create the same document twice

Every create call sends an Idempotency-Key, so a retry after a request that actually succeeded returns the same document instead of creating, and charging, another one. If your own code can repeat an operation (a job that retries, a user who clicks twice), pass a key that is stable for that operation:
The API keeps each key for 24 hours per project. The same key with a different body fails with 422 idempotency_key_reused.

Errors that don’t come from the API

These are raised by the SDK itself, so they aren’t DocondaError:
  • No API key: the constructor throws Error (Python: ValueError).
  • Bytes without a file name in convert or updateFile (Python: also files.upload): Error (Python: ValueError).
  • download(id, kind) for a kind the document doesn’t have: Error (Python: ValueError).
  • verifyWebhook with a bad signature or a timestamp more than 300 s off: Error (Python: ValueError).

Next steps

Error codes

Every code the API returns.

Webhooks

Get notified instead of waiting.

SDK reference

Every method and what it returns.