Errors

Status codes (public v1)

Status	Meaning	Typical cause
`200`	Success	Valid key and query
`400`	Invalid query parameters	Zod validation failed (`limit`, `status`, dates, …)
`401`	Unauthorized	Missing header, wrong format, invalid/expired key
`500`	Internal server error	Unexpected server failure

Public v1 list routes do not currently return 403 for plan gates on the read path (auth is “valid key → org data”). Plan gating applies when creating API keys in the dashboard (apiAccessEnabled).

Error body

{
  "error": "Unauthorized",
  "message": "API key required in Authorization header"
}

Validation failures may include structured Zod issues:

{
  "error": "Invalid query parameters",
  "details": [
    {
      "code": "too_big",
      "maximum": 100,
      "type": "number",
      "path": ["limit"],
      "message": "Number must be less than or equal to 100"
    }
  ]
}

OpenAPI schema: publicErrorSchema (error, optional message, optional details).

Client guidance

Situation	Action
`401`	Fix key configuration; do not retry blindly
`400`	Fix query params; do not retry the same payload
`500`	Retry with exponential backoff; log `requestId` if you have edge logs
Network errors	Retry with backoff; make sync jobs idempotent

Always check HTTP status before assuming a data array exists.

Get started

Core resources

Examples

Errors

Errors

Status codes (public v1)

Error body

Client guidance

​Errors

​Status codes (public v1)

​Error body

​Client guidance

Errors

Status codes (public v1)

Error body

Client guidance