Errors

Every error the E-Signing API can return, with a stable machine-readable code you can branch on.

Every error response has the same shape. Read error.code — it's a stable, machine-readable value. The message is for humans and may change at any time, so never branch on the message text.

Error shape

{
  "error": {
    "code": "unknown_signer_role",
    "message": "One or more recipient roles do not match this template.",
    "details": { }
  }
}

details is optional and, when present, carries structured context about the error.

Error codes

HTTP	`error.code`	Meaning
`401`	`missing_api_key`	No `X-API-Key` header on the token request.
`401`	`invalid_api_key`	The key is unknown, revoked, expired, or not a live-mode key.
`401`	`missing_token`	No `Authorization: Bearer` token was sent.
`401`	`invalid_token`	The token is malformed or expired. Request a new one.
`401`	`key_revoked`	The key behind this token was revoked or rotated — its tokens no longer work.
`403`	`insufficient_scope`	The key doesn't carry the scope this endpoint requires.
`403`	`forbidden`	The key's owner lacks the underlying permission, or API access isn't in your plan.
`403`	`signing_links_disabled`	The envelope doesn't share signing links with the sender.
`402`	`quota_exceeded`	No remaining API signature requests (on send).
`403`	`quota_exceeded`	A resource limit was reached (for example, the contact limit).
`404`	`template_not_found`	No template with that id exists in your company.
`404`	`envelope_not_found`	No envelope with that id exists in your company.
`404`	`webhook_not_found`	No webhook subscription with that id exists in your company.
`422`	`unknown_signer_role`	A recipient role doesn't match the template, or a locked role was supplied.
`422`	`sender_not_found`	`sender_email` isn't an active user with an eSignature seat in your company.
`422`	`validation_failed`	The request body is malformed or missing a required field.
`429`	`rate_limited`	Too many requests — back off and retry.
`5xx`	`send_failed`	The envelope was created but couldn't be sent, so it was discarded. Nothing was delivered.
`500`	`internal_error`	Something went wrong on our side. Safe to retry.

Why some errors are deliberately vague

On the token endpoint, "no such key", "revoked", "expired", and "not live-mode" all return the same 401 body. Likewise, a template in another company and a template that doesn't exist both return 404 template_not_found. This is intentional — a more specific error would let someone probe which ids or keys exist.

Handling errors well

Branch on error.code, never on message.
Retry 5xx, 429, and network errors with backoff. Don't retry 4xx — the request reached us and was rejected; fix the request instead.
Refresh on 401 invalid_token by exchanging your key for a new token. If you get key_revoked, the key itself was revoked — mint a new one in Settings → API Keys.
Treat quota_exceeded as a plan signal, not a transient error — it clears when the period resets or your plan is upgraded.

Error codes

Handling errors well

On this page