Errors

The API returns a small set of statuses and each has a single meaning, so your integration can decide what to do from the code alone. This page describes each status, the body that comes with it and why an envelope the credential cannot access returns 404.

Status codes

Status	Meaning	Action
400	Malformed request or failed validation	Compare the body with the schema in the API reference; dates must be ISO-8601
401	Credentials rejected: no token, an expired token (a token is valid for 300 s) or a token the realm will not validate	Request a new token and check the Bearer prefix. Both SDKs refresh the token and retry once before reporting this status
403	Authenticated, but the credential lacks the organization permission	The operation is a management operation that exists only in the UI, or the token has no bb_sign_org_id. See Machine authentication
404	The resource does not exist, or belongs to another organization or a workspace the credential cannot see. Deliberately indistinguishable	Check the id; if the workspace is the issue, ask an admin to grant the credential a role there
409	The resource is not in a state that allows the operation, for example sending an already-sent envelope	Read the envelope first and act on its status
422	A business rule rejected the request, for example sending an envelope with no document or no signer	Fix the envelope and try again
429	An organization quota is exhausted. The body says which one	Ask the platform administrator to raise or renew the quota; the SDKs retry this status
0 (SDKs only)	The request got no answer: it never reached bb-sign or the reply was lost	For a POST, list before you retry (see below)

401 and 403 are produced by the security filter chain and carry no body. Every other error carries an ErrorResponse.

A 429 always indicates an exhausted quota; the API does not apply rate limits.

Error body

{
  "status": 404,
  "error": "Not Found",
  "code": "WORKSPACE_NOT_FOUND",
  "message": "Workspace not found",
  "path": "/api/v1/envelopes",
  "timestamp": "2026-10-10T14:22:31Z",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Field	Type	Always present	Meaning
status	integer	yes	The HTTP status
error	string	yes	The HTTP reason phrase
code	string	yes	A stable machine-readable code, such as WORKSPACE_NOT_FOUND or NOT_FOUND. Base your logic on this field, not on message
message	string	yes	Human-readable text; its wording may change
path	string	yes	The request path
timestamp	date-time	yes	When the error was produced
traceId	string	no	Include it when you contact support; it locates the request in our logs
quota	QuotaViolation	no	Only on 429

QuotaViolation

{
  "status": 429,
  "error": "Too Many Requests",
  "code": "QUOTA_EXCEEDED",
  "message": "Organization quota exhausted",
  "path": "/api/v1/envelopes",
  "timestamp": "2026-10-10T14:22:31Z",
  "quota": { "dimension": "envelopes", "current": 500, "limit": 500 }
}

Field	Type	Meaning
dimension	string	The affected quota: number of envelopes or storage used
current	integer	The organization’s usage when the request was refused
limit	integer	The quota’s limit

The platform administrator sets quotas and org admins view them in the UI; see Quotas.

404 instead of 403

Isolation between organizations

An envelope or workspace that belongs to another organization, or sits in a workspace where the credential holds no role, returns 404, the same as an id that was never issued. This way, one organization cannot confirm that another’s resources exist. Within your own organization, a workspace the credential cannot create in returns 404 WORKSPACE_NOT_FOUND, and envelopes in workspaces it cannot read do not appear in lists.

403 is reserved for organization-level denials: the token lacks a permission the operation requires, or does not carry the org claim.

Errors in the SDKs

Both SDKs turn every non-2xx response into a single exception type that carries the status and nothing else: neither the Response object nor the headers. Logging the error therefore does not expose your Authorization header. Messages never include your secret or access token, even when bb-sign’s response contains them.

	JavaScript	Java
Type	BbSignError	BbSignException
Status	error.statusCode	e.statusCode()
No answer	statusCode === 0	statusCode() == 0

try {
  await client.envelopes.createEnvelope({ createEnvelopeRequest: request })
} catch (error) {
  if (error.statusCode === 0) {
    // Never reached bb-sign, or the answer was lost. List before you send again.
  }
}

try {
    client.execute(client.envelopes().createEnvelope(request));
} catch (BbSignException e) {
    if (e.statusCode() == 0) {
        // Never reached bb-sign, or the answer was lost. List before you send again.
    }
}

Neither SDK retries a POST whose response was not received: the envelope may already exist, and these are agreements sent to real people. GET requests are retried on 5xx errors and transport failures; 429 and 503 are retried for every method, because they indicate the server did not process the request. The walkthrough shows how to list before retrying.