Skip to main content
All errors return structured JSON with a code, human-readable message, and correlationId.

​
Typical error payload

{
  "status": 403,
  "code": "FORBIDDEN",
  "message": "Scope org_write is required",
  "correlationId": "7f91a0cd-..."
}

​
Common scenarios

  • Auth issues: refresh or request the correct scopes
  • Validation: fix request shape or business rule violations
  • Rate limiting: handle 429 with backoff and respect Retry-After
  • Server errors: retry with idempotency and backoff

​
Observability

  • Log correlationId, HTTP status, and request path.
  • Include correlationId when opening a support ticket; it maps directly to backend traces.
What to log per request:
  • HTTP method, path, status, correlationId, and code
  • Request/response timestamps
  • Idempotency key (for write flows)

​
Retry patterns

  • Do not retry 4xx except 429.
  • Use exponential backoff (e.g., 1s, 2s, 4s) with jitter.
  • Keep booking/payment operations idempotent to safely retry.