Error codes

Every error response is JSON with the same outer shape:

{ "error": { "code": "name_taken", "message": "a branch with this name exists" } }

code is stable and snake_case; match on it. message is for people and can change. A few codes add keys inside error (listed below). The HTTP status says the class of failure; the code says which one.

The data API adds detail, hint and sqlstate to errors that come from Postgres. See Data API errors.

Management, login and gateway codesCopy Anchor Link

These come from the management API, the login API (the dashboard sign-in and app users) and the gateway. Where a code has two statuses, each row says when.

Request and authenticationCopy Anchor Link

Members, access and invitesCopy Anchor Link

Any project route can answer the first four rows. See Access per route for which level each route needs.

Two more refusals use general codes. A grant or override below Admin that lists an owner-level, LOGIN or reserved role, or a role whose chain reaches one, is 422 invalid_request, and so is a grant at any level (Admin too) whose role chain holds ADMIN on another role; the message names the role, its chain and the database (error.role, error.chain, error.database_id), and invites and approvals also name the grant's project (error.project_id). A Developer who acts as such a role, or creates a data key bound to one, gets 403 forbidden with required: "admin".

Projects and databasesCopy Anchor Link

BranchesCopy Anchor Link

Table APICopy Anchor Link

Schema mergesCopy Anchor Link

Merge routes also answer the general codes above: not_found for an unknown merge (or another tenant's, or one of another database), branch_not_ready on a start, rehearse, apply and retry (a branch of the merge isn't ready), backup_branch and invalid_request on a start (a step id with :, ., a control character or phase1 is a 422 invalid_request on a save), and conflict with 409 when the merge is in a state that can't take the request (for example editing a merge that is applying, or exporting a plan before there is one). See Merging schema between branches.

A merge that fails while running (failed, stale) shows its reason in the merge's own error and failed_phase, not as an HTTP error. The worker starts the error with a code where it knows the cause: merge_stale: (the target changed; nothing of the plan's transaction was applied), merge_target_changed: and merge_target_gone: (the plan's transaction is no longer on the target, or the target is gone: failed with no phase), merge_half_applied: (a recompute found the plan's transaction on the target: failed in online), and merge_resolution_refused: (a saved choice was refused: a draft). An apply interrupted before its transaction committed returns to rehearsed with an error that starts "interrupted before the plan's transaction committed". Merging schema lists them.

Login roles and data API keysCopy Anchor Link

App usersCopy Anchor Link

SQL editorCopy Anchor Link

Data API codes on the gatewayCopy Anchor Link

The gateway authenticates data API requests before they reach the data API, and answers with the data API's error body. These codes come from the gateway, with the statuses below.

A bad user token never falls back to the key's own role.

Data API errorsCopy Anchor Link

The data API (POST /data/v1/query, GET /data/v1/schema) answers with:

{
  "error": {
    "code": "conflict",
    "message": "duplicate key value violates unique constraint \"users_email_key\"",
    "detail": "Key (email)=(a@example.com) already exists.",
    "sqlstate": "23505"
  }
}

detail, hint and sqlstate are present only on a database error that Chelabase maps to a code, and carry Postgres's own text. Everything else has code and message only. A 503 and a 500 never show Postgres's text; the 500 message carries a request id and the details go to the log with it.

On a data API route the gateway also answers an unknown path (404) or a wrong method (405) with invalid_query, and the 405 carries Allow.

503 and Retry-AfterCopy Anchor Link

Every 503 from the data API carries Retry-After: 1 when the gateway answers it, 2 when the data API service does. Causes:

• the branch's database can't be reached, refuses the connection, or is out of connections or resources (Postgres classes 08, 28 and 53, and 57P01 to 57P03);
• no connection to the branch in time, or too many connections in use;
• the service can't look up the branch, or the branch isn't ready;
• the key's role can't be used right now (dropped, or its grant is gone until the bootstrap runs again);
• the data API's schema is missing; it will be reinstalled;
• the gateway can't check the key or the user's session.

The 503 message is fixed text.

For how to send queries and handle these errors, see the Data API guide.