Error handling

Most failures return the same envelope: an errors array, each entry with a message and an optional metadata object carrying the machine-readable detail.

{
  "errors": [
    {
      "message": "The length of 'Name' must be at least 2 characters. You entered 1 characters.",
      "metadata": null
    }
  ]
}

The exception is the front-door checks — the 401 and the four 403s raised before your request reaches the application — which return a single message property:

{ "message": "User should be authenticated." }

Branch on the status code and the metadata keys, never on message text. Messages are written for people and get reworded.

Status codes

Status	Meaning	Retry?
`400`	The request is not valid for this envelope's state, or a field is wrong.	No.
`401`	No identity could be established from the token.	No.
`402`	The account has no envelope balance.	No — buy envelopes.
`403`	Identified, but not allowed.	No — see the message.
`404`	The resource does not exist, or is not yours.	No.
`409`	Another publish is in flight for this account.	Yes, shortly.
`422`	The request is well formed but cannot be carried out.	No.
`429`	Rate limit exceeded.	Yes, after `Retry-After`.
`500`	Unexpected failure on our side.	Yes, with backoff.

401 Unauthorized

Returned whenever no identity could be established: no header, wrong length, unknown or revoked token — and also when the user or the membership behind the token has been deactivated, because those are filtered out of the lookup rather than reported on their own.

{ "message": "User should be authenticated." }

403 Forbidden

You were identified, but refused. Seven conditions produce it.

Message	What it means	Who fixes it
`Account should be active.`	The account was deactivated.	Signater support.
`API access requires a Business plan or higher.`	The plan does not include the API.	An account administrator, in Billing.
`Sandbox mode is disabled.`	The token is a sandbox token and sandbox is off.	An account administrator, in Account settings.
`User should be an administrator.`	The endpoint is restricted to administrators.	Use an administrator's token.
`PIX validation is disabled for this account.`	The envelope asks for Pix identity validation.	An account administrator, in Account settings.
`WhatsApp validation is disabled for this account.`	The envelope asks for WhatsApp one-time codes.	An account administrator, in Account settings.
`WhatsApp communication is disabled for this account.`	A signer is set to receive WhatsApp messages.	An account administrator, in Account settings.

The last three are disabled by default on accounts outside Brazil. If you are integrating from elsewhere and a perfectly valid envelope is refused, this is almost always why. They are account settings, not plan limits — upgrading does not lift them.

The first four return {"message": "..."}; the last three use the errors envelope.

402 Payment Required

Publishing debits one envelope from the account balance. With none available, publication is refused and the envelope stays where it was:

{
  "errors": [
    {
      "message": "The account has no envelope balance available to publish this envelope.",
      "metadata": {}
    }
  ]
}

Add envelopes or change plan at app.signater.com/settings/billing/plans. 402 is reachable only on publish.

409 Conflict

Publishing takes a short lock, and the lock is per account, not per envelope — two publishes of different envelopes on the same account can contend.

{
  "errors": [
    {
      "message": "Unable to process envelope publish at this time. Please try again in a few moments.",
      "metadata": {}
    }
  ]
}

Wait a moment and repeat. See Retries and idempotency for why that is safe.

422 Unprocessable Entity

Two different situations produce a 422, and they carry different bodies.

On publish — the envelope is missing something it needs, with no metadata:

{"errors":[{"message":"Envelope should have at least one signer","metadata":{}}]}

On create and update — the envelope is bigger than the plan allows, with the limit named:

{
  "errors": [
    {
      "message": "Signer count exceeds the plan limit.",
      "metadata": { "maxSigners": "50" }
    }
  ]
}

Key	Limit
`maxSigners`	Signers per envelope. Business: 50. Enterprise: unlimited.
`maxDocuments`	Documents per envelope. Business: 50. Enterprise: unlimited.

Above every plan sits a hard cap of 200 signers per envelope. That one reports An envelope may have at most 200 signers. and carries no metadata, so do not key on maxSigners alone.

Updating an envelope that already exceeds a limit is allowed: existing counts are grandfathered, and the metadata reports the effective limit rather than the plan's.

Document size is not part of this. The upload ceiling is a flat 100 MB on every plan, and an unreadable PDF returns 422 with The PDF file is corrupted or uses unsupported compression.

429 Too Many Requests

The limit is 1,000 requests per 10-minute sliding window, per token. The hundred requests past the limit are queued and simply run slowly; beyond that:

{"errors":[{"message":"Rate limit exceeded. Retry after the number of seconds given in the Retry-After header.","metadata":{}}]}

Honour Retry-After — the window releases capacity one segment at a time, so an earlier retry is refused again.

One endpoint has its own cooldown: manual-reinvite-to-review returns 429 if the same envelope was re-invited too recently. That is a per-envelope guard against spamming signers, not the global limit.

Request telemetry

Every response carries a trace id:

Thirty-two hexadecimal characters, no dashes. Log it — sending it to support turns an investigation into a lookup.

Status codes#

401 Unauthorized#

403 Forbidden#

402 Payment Required#

409 Conflict#

422 Unprocessable Entity#

429 Too Many Requests#

Request telemetry#