Errors

The single error envelope, every status and code the public API returns, and what to do about each.

Every error uses one envelope, so a client needs one parser.

The envelope

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This token lacks the 'export' scope",
    "details": { "required_scope": "export" }
  }
}

Branch on code, which is stable, and show message to people. details carries structured extras.

Codes#

Status	Code	Meaning and what to do
400	`INVALID_FILTER`, `INVALID_BODY` and similar	The request was malformed. Fix it; retrying unchanged will fail the same way.
401	`INVALID_TOKEN`	Unknown, expired or revoked token, or you lost access to the workspace. Create a new token.
401	`TOKEN_AUDIENCE_MISMATCH`	An OAuth connector token was used on the REST API. Use a personal token.
402	(no stable code)	The workspace is out of coins (`ask`). Top up, or use search, which is free.
403	`INSUFFICIENT_SCOPE`	The token lacks a scope. `details.required_scope` names it.
403	`SESSION_REQUIRED`	The endpoint is not part of the public API.
403	`TOKEN_OWN_NOTES_ONLY`	A token can edit only notes its owner created.
403	`READ_ONLY_ROLE`	Viewers cannot make changes.
403	`FEATURE_DISABLED`	A workspace feature flag is off (for example streamed answers).
404	`NOT_FOUND`	No such item or job, or one you cannot read. The two are indistinguishable on purpose.
409		An export has not finished, failed or expired.
413		A synchronous ZIP export has more than 500 items. Use an asynchronous export.
422	`SOURCE_UNSUPPORTED`	A link Breno cannot read. Nothing was saved.
429	`RATE_LIMIT_EXCEEDED`	Slow down. Wait for `Retry-After` seconds.

Retrying#

Retry only what can succeed later: 429 (after Retry-After), 409 on an export download (it is not finished), and network failures or 5xx (with backoff). Never retry 400, 401, 403 or 422 unchanged. For upload and capture, send an Idempotency-Key so a retry cannot duplicate work.

Reference#

A longer list of codes the platform can return, including ones outside the public API, is in the repository's docs/api/error-codes.md.