Error handling

The REST API uses RFC 9457 Problem Details for every error. Every error response has Content-Type: application/problem+json and a consistent JSON shape.

Error response format

{
  "type": "/errors/unique-constraint",
  "title": "Conflict",
  "status": 409,
  "detail": "Unique constraint \"students_email_key\" violated. Key (email)=(alice@example.com) already exists.",
  "instance": "/api/rest/students",
  "errors": [
    { "field": "email", "rule": "unique", "message": "The value for email already exists" }
  ]
}

Field	Type	What it tells you
`type`	String	A stable, machine-readable URI identifying the error category. Switch on this in your code.
`title`	String	A short human-readable summary, paired with the HTTP status.
`status`	Number	The HTTP status code, duplicated in the body for convenience.
`detail`	String	A human-readable explanation specific to this occurrence.
`instance`	String	The request path that produced the error.
`errors`	Array	Field-level details when applicable (validation, constraints).

Status code reference

4xx — client errors

Status	Type	Meaning
400	`/errors/bad-request`	Malformed request.
400	`/errors/missing-project-id`	Missing `X-Project-ID` header.
400	`/errors/complexity-limit`	Query exceeded depth or relation limits.
401	`/errors/unauthorized`	Missing or invalid auth token.
403	`/errors/forbidden`	Authenticated, but not allowed.
404	`/errors/item-not-found`	Record does not exist.
404	`/errors/not-found`	Resource not found (composite PK, etc.).
404	`/errors/table-not-found`	Table doesn’t exist in the schema.
405	`/errors/view-is-readonly`	Tried to write to a view.
409	`/errors/unique-constraint`	Duplicate value on a unique field.
422	`/errors/validation-failed`	Body or parameters fail validation.
422	`/errors/foreign-key-constraint`	Referenced record doesn’t exist.
422	`/errors/not-null-constraint`	Required field is missing or null.
422	`/errors/check-constraint`	Field value violates a check constraint.
429	`/errors/rate-limit-exceeded`	Too many requests.

5xx — server errors

Status	Type	Meaning
500	`/errors/internal-error`	Unexpected server error.
504	`/errors/query-timeout`	Database query exceeded time limit.

Common errors

Validation (422)

Required fields missing or wrong types.

{
  "type": "/errors/validation-failed",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "One or more fields failed validation",
  "instance": "/api/rest/students",
  "errors": [
    { "field": "email", "rule": "required", "message": "The field 'email' is required" },
    { "field": "age", "rule": "type", "message": "Expected number, got string" }
  ]
}

Unique constraint (409)

Duplicate value on a unique column. The errors[].field tells you which column.

{
  "type": "/errors/unique-constraint",
  "title": "Conflict",
  "status": 409,
  "detail": "Unique constraint \"students_email_key\" violated. Key (email)=(alice@example.com) already exists.",
  "instance": "/api/rest/students",
  "errors": [
    { "field": "email", "rule": "unique", "message": "The value for email already exists" }
  ]
}

For handling this without the read-then-write race condition, use a GraphQL upsert.

Foreign key (422)

Referencing a related record that doesn’t exist.

{
  "type": "/errors/foreign-key-constraint",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Foreign key constraint violated. Referenced record does not exist.",
  "instance": "/api/rest/students",
  "errors": [
    { "field": "cityId", "rule": "foreign_key", "message": "Referenced record in 'cities' does not exist" }
  ]
}

Not found (404)

{
  "type": "/errors/item-not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Record not found",
  "instance": "/api/rest/students/00000000-0000-0000-0000-000000000000"
}

Rate limit exceeded (429)

{
  "type": "/errors/rate-limit-exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Try again in 30 seconds.",
  "instance": "/api/rest/students"
}

The response includes rate-limit headers — back off using Retry-After:

Header	What it tells you
`Retry-After`	Seconds to wait before retrying.
`X-RateLimit-Limit`	Requests allowed per window.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Seconds until the window resets.

Query timeout (504)

{
  "type": "/errors/query-timeout",
  "title": "Gateway Timeout",
  "status": 504,
  "detail": "Database query exceeded the maximum execution time",
  "instance": "/api/rest/students"
}

Tighten the filter, paginate, add an index, or move to a view that pre-computes the result.

Field names in errors

Database column names are converted to camelCase in error messages — a constraint on created_at reports the field as createdAt. This matches what you send and receive in JSON bodies.

Handling errors in code

Switch on status first, then on type for ambiguous statuses:

Status	What to do
400	Fix the request. Don’t retry.
401	Refresh the auth token. Retry once.
403	Surface a “no permission” message. Don’t retry — same user, same outcome.
404	Treat as the resource not existing.
409	Show the user a “duplicate” message. For automatable cases, switch to upsert.
422	Surface field-level errors back to the user. Don’t retry the same payload.
429	Honor `Retry-After` with exponential backoff.
5xx	Retry with backoff. If persistent, alert.

async function call(url, init) {
  const res = await fetch(url, init);
  if (!res.ok) {
    const problem = await res.json();
    switch (problem.type) {
      case "/errors/unique-constraint":
        throw new DuplicateError(problem.errors?.[0]?.field);
      case "/errors/rate-limit-exceeded":
        const wait = parseInt(res.headers.get("Retry-After") ?? "1", 10);
        await new Promise((r) => setTimeout(r, wait * 1000));
        return call(url, init);
      default:
        throw new ApiError(problem);
    }
  }
  return res.json();
}

FAQ

Why are validation errors 422 and not 400?

400 means the request itself was malformed (bad JSON, wrong content type). 422 means the request was syntactically fine but semantically invalid — required fields missing, types wrong, constraints violated. The distinction tells your code whether to retry the same payload or fix the request shape first.

What's the difference between 401 and 403?

401 means “we don’t know who you are” — the auth token is missing, expired, or invalid. 403 means “we know who you are, but you can’t do this” — the role doesn’t have the necessary permission. Refresh tokens for 401; surface a permission error for 403.

Should I retry on 5xx?

Yes, with exponential backoff. Most 5xx errors are transient. Cap retries at 3–5 and alert if they keep failing.

Can I get more detail than `detail`?

The errors array gives field-level reasons. For complex cases, the instance URL points to the request that failed — useful for support tickets.

What happens to a `Idempotency-Key` request when it errors?

2xx and 4xx responses are cached and returned on retry with the same key. 5xx responses are not cached, so retries actually re-run the operation. See Idempotency.

Home

Blueprint

Design

Frontend

Backend

Assets

Error response format

Status code reference

4xx — client errors

5xx — server errors

Common errors

Validation (422)

Unique constraint (409)

Foreign key (422)

Not found (404)

Rate limit exceeded (429)

Query timeout (504)

Field names in errors

Handling errors in code

FAQ

​Error response format

​Status code reference

​4xx — client errors

​5xx — server errors

​Common errors

​Validation (422)

​Unique constraint (409)

​Foreign key (422)

​Not found (404)

​Rate limit exceeded (429)

​Query timeout (504)

​Field names in errors

​Handling errors in code

​FAQ

Error response format

Status code reference

4xx — client errors

5xx — server errors

Common errors

Validation (422)

Unique constraint (409)

Foreign key (422)

Not found (404)

Rate limit exceeded (429)

Query timeout (504)

Field names in errors

Handling errors in code

FAQ