Reference

Error codes reference

The specific code values you are most likely to see on the public API. The envelope and the generic per-status codes are described in Errors.

This list is not exhaustive and new codes are added over time. Handle unknown codes by HTTP status.

Authentication and access#

Code	Status	Meaning and fix
`unauthenticated`	401	Missing, invalid, revoked or expired key, or the key's creator left the organization. Create a new key.
`insufficient_scope`	403	The key lacks the scope for this method and path. `message` names it (for example `Missing scope documents:write`).
`ip_not_allowed`	403	The key has an IP allowlist and the request came from another address (named in `message`). Call from an allowed address or edit the list. Restrict a key to IP addresses
`forbidden`	403	The endpoint is not available to API keys, the creator's role is not sufficient (for example webhooks need an organization admin), or a key was used on another organization's custom domain.
`document_forbidden`	403	Only the document creator or an organization admin may read signing links.
`template_forbidden`	403	The template is not shared with the key's creator.
`template_public_link_forbidden`	403	Only organization or team admins can enable public links.
`flow_forbidden`	403	The key's creator cannot access this flow.
`email_not_verified`	403	The sender (key creator) must confirm their email address before sending.

Code	Status	Meaning and fix
`feature_not_in_plan`	402	The plan does not include the feature in `extra.feature` (for example `api_keys`, `webhooks`). Upgrade in Billing.
`documents_per_month`	402	Monthly document quota reached; `extra` has `current` and `limit`.
`sms_not_in_plan`	402	SMS verification is not in the plan. Use `EMAIL_OTP` or upgrade.
`sms_quota_exceeded`	402	Monthly SMS allowance used up; `extra` has `current` and `limit`.
`subscription_past_due`	402	The organization is read-only until the subscription is paid.
`storage_quota_exceeded`	413	Storage limit reached. Delete old documents or upgrade.
`invite_daily_cap`	429	Daily invitation cap for new self-serve organizations on managed email.

Code	Status	Meaning and fix
`document_not_found`	404	No such document in your organization (or it is not visible to the key's creator).
`recipient_not_found`	404	The recipient ID does not belong to this document.
`document_not_draft`	409	Fields can only be changed while the document is a `DRAFT`.
`document_not_pending`	409	Reminders and signing links need a `PENDING` document.
`document_not_cancellable`	409	Only `DRAFT` or `PENDING` documents can be cancelled.
`recipient_not_correctable`	409	The recipient already signed or was finalized.
`recipient_not_invited`	409	The recipient has no active invitation (not their turn yet, or already done).
`document_no_signers`	422	Add at least one `SIGNER` or `APPROVER` before sending.
`signer_missing_signature_field`	422	Every signer needs a `SIGNATURE` field; the message lists the emails.
`field_recipient_invalid`	422	A field's `recipient_id` is not a recipient of this document.
`invalid_pdf`, `pdf_sanitize_failed`	422	The PDF could not be parsed or safely processed. Re-export it (for example "Print to PDF").
`team_not_found`, `folder_not_found`	422	`team_id` or `folder_id` is not valid for your organization.
`qes_disabled`	422	A recipient uses the `QES` signing method but qualified signing is not configured for the organization.
`invalid_cursor`	422	The pagination cursor is malformed; restart from the first page.

Code	Status	Meaning and fix
`template_not_found`	404	No such template in your organization.
`template_no_signer`, `template_roles_incomplete`	409	The template's recipient slots are not set up for this use (for example no signer slot, or a role without a person).
`invalid_recipient_index`, `fields_out_of_range`	422	A field points at a recipient slot or page that does not exist.
`invalid_team`	422	The team is not valid for this template.
`phone_required`	422	The template requires a phone number for the signer.

Code	Status	Meaning and fix
`flow_not_found`, `flow_run_not_found`	404	No such flow or run in your organization.
`flow_not_published`, `flow_not_runnable`	409	Publish the flow (and make sure it is active) before starting runs.
`flow_run_finished`, `flow_run_conflict`	409	The run already finished, or changed while you acted on it.
`approval_not_pending`	409	No approval is waiting at that step.
`flow_invalid`	422	The flow definition has errors; `extra.errors` lists them by step.
`trigger_template_required`	422	Trigger `document_completed_of_template` needs `trigger_template_id`.

Code	Status	Meaning and fix
`validation_error`	422	Schema validation failed; `detail` lists field errors.
`idempotency_key_too_long`	400	`Idempotency-Key` is over 200 characters.
`idempotency_key_reused`	422	The key was already used with a different body. Use a new key. See Idempotency.
`payload_too_large`	413	Body over 30 MB, or the document JSON `payload` over 64 KB.
`rate_limited`	429	Over 100 requests per second for this key. Honor `Retry-After`.