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
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.
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
Everycreate 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:
422 idempotency_key_reused.
Errors that don’t come from the API
These are raised by the SDK itself, so they aren’tDocondaError:
- No API key: the constructor throws
Error(Python:ValueError). - Bytes without a file name in
convertorupdateFile(Python: alsofiles.upload):Error(Python:ValueError). download(id, kind)for a kind the document doesn’t have:Error(Python:ValueError).verifyWebhookwith 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.