Error Codes

All API errors return a JSON body with a status and message field:

{
  "status": 422,
  "message": "Column 'email' cannot be null"
}

2xx — Success

Code	Name	When you see it
200	OK	GET / PUT succeeded, response body contains data
201	Created	POST succeeded, new row inserted
204	No Content	DELETE succeeded, no body returned

4xx — Client Errors

Code	Name	Common Cause
400	Bad Request	Malformed JSON body or invalid query param format
401	Unauthorized	Missing or expired Bearer token
403	Forbidden	Valid token but insufficient role/permission for this resource
404	Not Found	Table or database name does not exist — check /{db}/{table} path
405	Method Not Allowed	HTTP verb not supported on this endpoint
409	Conflict	Duplicate entry — unique constraint violation (e.g. email already exists)
422	Unprocessable Entity	Column value violates schema constraint (null, type mismatch, length exceeded)
429	Too Many Requests	Rate limit exceeded — back off and retry after the Retry-After header value

5xx — Server Errors

Code	Name	What to do
500	Internal Server Error	Unexpected server-side failure — check your request and retry
502	Bad Gateway	Upstream database unreachable — retry after a short delay
503	Service Unavailable	Server under maintenance or overloaded — retry with exponential backoff

Header Errors

These are returned as 401 or 403 depending on what is missing:

Header	Missing → Error
X-Org-Id	401 Unauthorized
X-Project-Id	401 Unauthorized
X-Space-Id	401 Unauthorized
X-User-Id	401 Unauthorized
X-User-Roles	403 Forbidden — role cannot be resolved

Pagination Errors

Scenario	Code	Message
ps exceeds 50	400	"Page size cannot exceed 50"
pg is negative	400	"Page number must be 0 or greater"
pg beyond total pages	200	Empty data: [] array — not an error

Example Error Responses

401 — Missing header

{
  "status": 401,
  "message": "Unauthorized: X-Org-Id header is required"
}

404 — Wrong table name

{
  "status": 404,
  "message": "Table 'usres' not found in database 'demo_db'"
}

409 — Duplicate email

{
  "status": 409,
  "message": "Duplicate entry 'alice@example.com' for key 'email'"
}

422 — Schema violation

{
  "status": 422,
  "message": "Column 'name' cannot be null"
}

429 — Rate limited

{
  "status": 429,
  "message": "Too many requests. Retry after 30 seconds.",
  "retry_after": 30
}