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
`403`	Forbidden	Missing scope (`WWW-Authenticate: Bearer error="insufficient_scope"`) or the plan no longer allows Public API access (`API_ACCESS_DISABLED`)
`429`	Too many requests	API key/org/IP rate limit exceeded
`500`	Internal server error	Unexpected server failure

Public v1 list routes re-check apiAccessEnabled on every request. Existing keys stop working if an organization downgrades below the Public API tier.

Error body

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

A valid key without the route’s scope:

{
  "error": "Forbidden",
  "message": "Insufficient scope"
}

Response header: WWW-Authenticate: Bearer error="insufficient_scope". Plan-gated failures use a stable code:

{
  "error": "Forbidden",
  "code": "API_ACCESS_DISABLED",
  "message": "Public API access is not available on the current organization plan. Upgrade to Professional or contact Cicini support."
}

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"
    }
  ]
}

Rate-limit failures include Retry-After and X-RateLimit-* headers:

{
  "error": "Too Many Requests",
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded. Please try again later.",
  "retryAfter": 42
}

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

Client guidance

Situation	Action
`401`	Fix key configuration; do not retry blindly
`403`	Check the key’s scopes; if the code is `API_ACCESS_DISABLED`, restore the plan
`429`	Wait at least `Retry-After` seconds before retrying
`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

Status codes (public v1)

Error body

Client guidance