Skip to content
excalibase
errors
Connectstable

Errors

A request the database or the engine refuses answers a 4xx a client can act on, with a stable code, a message that names no SQL, file or line, and the constraint or column it is about when known. The message is the database's primary message only: never a PL/pgSQL context, the row values of a Detail line, or a stack trace.

REST

{
  "code": "unique_violation",
  "message": "duplicate key value violates unique constraint \"issues_pkey\"",
  "error": "duplicate key value violates unique constraint \"issues_pkey\"",
  "constraint": "issues_pkey"
}

error repeats message for older clients.

StatuscodeMeaning
409unique_violationA primary key or unique constraint is already taken; constraint names it. Send Prefer: resolution=merge-duplicates to upsert instead.
400foreign_key_violationThe referenced row does not exist, or a row still references this one; constraint names the key.
400check_violationA CHECK constraint failed; constraint names it.
400not_null_violationA required column has no value; column names it.
400exclusion_violationAn EXCLUDE constraint failed; constraint names it.
400raised_exceptionA trigger or function raised an error (RAISE EXCEPTION); message is the raised text only.
400invalid_valueA value the column's type cannot hold, in a filter or the body (for example a malformed uuid); column names it when known.
400bad_requestA malformed filter, an unknown column or operator, a body that is not JSON, or a function call missing an argument; message says which.
405method_not_allowedA function that changes data called with GET; call it with POST.
406not_acceptableA single-object request (Accept: application/vnd.pgrst.object+json) matched other than one row.
403permission_deniedThe role holds no permission for the method, or for a column it tried to write (column names it). A column the project sets itself, such as an owner id, is refused the same way. Counting rows without allowAggregations is refused too.
403permission_check_failedA written row does not pass the role's permission check; the write rolls back whole.
404not_foundAn unknown table or function, or one the role cannot see.
500internal_errorA fault on the server's side. The body says nothing more; the cause is logged.

For example, the demo project lets anon read and add feedback posts but not change them:

curl -s -X PATCH "$BASE/$PROJECT_ID/api/v1/feedback_posts?id=eq.1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "edited"}'
{
  "code": "permission_denied",
  "message": "PATCH is not permitted on feedback_posts",
  "error": "PATCH is not permitted on feedback_posts"
}

A table the role cannot select answers 404, the same as a table that does not exist.

GraphQL

A GraphQL request answers 200 with an errors array. The code (and constraint or column) travel in extensions:

{
  "errors": [
    {
      "message": "duplicate key value violates unique constraint \"issues_pkey\"",
      "extensions": { "code": "unique_violation", "constraint": "issues_pkey" }
    }
  ]
}

The codes are the ones in the table above.

The typed codes and statuses above are what the engine answers from build main-3151432 onward. On older builds a unique, foreign-key, check or trigger violation answers a 500, a malformed filter value answers 500, and a GraphQL error can carry the database's Detail line.