Errors

The error envelope

Every non-2xx response uses the same shape. Only error is always present; the remaining fields appear when they add something useful.

string

A stable machine-readable code, for example insufficient_scope. Branch on this, not on the human-readable text.

string

A human-readable explanation, safe to log.

string

A shorter human-readable summary, present on some responses.

object

Additional structured context — for validation failures, typically the offending fields.

string

On 403, the scope this endpoint needs.

array

On 403, the scopes your token actually holds.

Status codes

Status	Meaning	What to do
`400`	Malformed request or bad token exchange	Fix the request; do not retry unchanged
`401`	Token missing, expired, revoked or malformed	Get a new token, then retry once
`403`	Valid token, insufficient scope	Request a token with the scope named in `required_scope`
`404`	No such record, or not visible to the acting user	Check the ID and the user’s permissions
`404 Tenant Unknown`	`zivio-tenant-id` missing or unrecognised	Add the header; checked before authentication
`405`	Method not allowed on this path	Check the method against the API Reference
`422`	Validation failed, or the record is in the wrong state	Read `details` and correct the payload

A 404 does not always mean the record is absent — responses are scoped to what the acting user may see, so a record outside their permissions is indistinguishable from one that does not exist.

Worked examples

404 Tenant Unknown — before you get any further

A plain-text Tenant Unknown body, rather than the JSON envelope above, means the request never reached the API. The zivio-tenant-id header is missing or does not match a Zivio organisation, and it is checked before your token is.Your token and scopes are not the problem here. See Identifying your organisation.

401 — expired token

{
  "error": "invalid_token",
  "error_description": "The access token provided is expired, revoked, malformed, or invalid for other reasons"
}

Request a fresh token and retry. Retry once only — a second 401 means the credentials or the Authorization header are wrong, not the token’s age.

403 — missing scope

{
  "error": "insufficient_scope",
  "error_description": "The request requires higher privileges than provided by the access token",
  "required_scope": "projects:read",
  "provided_scopes": ["welcome:read"]
}

Retrying will not help — the token needs to be issued with projects:read. See Scopes.

422 — wrong state for the action

Workflow endpoints reject actions that do not apply to the record’s current state. For example, submitting a project that is not in draft, or one that fails publish validation.Some 422 responses are actionable rather than fatal: POST /projects/{id}/submit returns error: approver_selection_required together with an approver_selection array listing each step’s eligible approvers, so you can re-submit with approvers populated.

Handling errors well

Branch on the error code, never on error_description wording.
Retry 401 once after refreshing the token. Do not retry 403 or 422 — they need a different token or a different payload.
Log error, error_description and details together; details usually names the exact field at fault.

Get started

Authentication

Using the API

MCP server

Webhooks

Migration

The error envelope

Status codes

Worked examples

Handling errors well

​The error envelope

​Status codes

​Worked examples

​Handling errors well

The error envelope

Status codes

Worked examples

Handling errors well