Errors & retries

The API returns standard HTTP status codes with a JSON error body:

{
  "message": "JWT expired",
  "code": "PGRST301",
  "details": null,
  "hint": null
}

Status codes

Code	Means
`200` / `204`	Success (`204` on writes with no `Prefer: return=representation`)
`400`	Bad query — unknown filter operator, malformed JSON body
`401`	Missing / invalid / expired JWT
`403`	JWT valid but the operation is forbidden — e.g. updating a column outside the writable set, or writing to a read-only resource
`404`	Resource doesn’t exist on the version you addressed
`409`	Conflict — a write would violate a unique constraint
`416`	Range / pagination window out of bounds
`429`	Rate limit exceeded (600 req/min per source IP)
`5xx`	Server error — retry with backoff; report if it persists

On 429: honor the Retry-After header, then back off exponentially.
On 5xx: retry with exponential backoff and jitter; give up after ~5 attempts and alert.
On 401 with JWT expired: stop and rotate the token — retries won’t help.
Concurrency: cap at ~5 in-flight requests per source IP.
Log the full error body (message, code, hint) — hint often contains the fix.