Errors

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": {
    "code": "unknown_signer_role",
    "message": "One or more recipient roles do not match this template.",
    "details": { },
    "reference": "0190f3a2-7b6c-7e21-9a3f-2c9b1d4e5f60"
  }
}

details

Present only when there's something useful to say. Two cases are worth handling explicitly:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key is missing the required scope \"envelopes:send\".",
    "details": { "required_scope": "envelopes:send", "granted_scopes": ["templates:read"] }
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Slow down and retry after the indicated interval.",
    "details": { "retry_after": "15 minutes" }
  }
}

reference

A UUID identifying the server-side log entry for this failure. It appears on the errors we persist (5xx and 422) and is absent on auth and validation errors that carry no server-side log.

Log it. When you report a problem, quoting the reference lets us find the exact failure in one lookup instead of asking you to reproduce it.

Error codes

Fixing sender_fields_incomplete

This one surprises people, because the request is perfectly valid. It means the template has fields assigned to its own sender role ("Me") that are required and empty — so there is no complete document to send.

The API fills the sender's fields automatically from what's stored on the template; it cannot invent values. Fix it on the template, not in your request:

• give those sender fields a value on the template, or
• mark them optional, or
• remove them.

Then retry the same call.

Handling errors well

• Branch on error.code, never on message.
• Retry 5xx, 429, and network errors with backoff, honouring the Retry-After header on a 429. Don't retry other 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, then retry once. If you get key_revoked, the key itself was revoked — load the replacement key rather than retrying.
• Treat quota_exceeded as a plan signal, not a transient error — it clears when the period resets or your plan is upgraded. Retrying won't help, and on send it means nothing was delivered.
• send_failed means nothing went out. The envelope is deleted, so a retry creates a fresh one rather than duplicating a delivery.
• Log reference whenever it's present.