Core concepts

Errors and rate limits

Use HTTP status codes for broad handling and the response detail for the specific failure. Do not use 404 responses to infer resources outside the credential boundary.

Error shape

403 · application/json

{
  "detail": {
    "code": "missing_scope",
    "required": ["bookings:write"]
  }
}

Some framework-level validation failures return a structured detail array with the field location and validation message.

HTTP status codes

400client

Invalid cursor or malformed operation state.

401client

Missing, invalid, expired, or revoked API key.

403client

Credential lacks the required scope or its support owner is inactive.

404client

Resource does not exist in the credential’s studio or permitted locations.

409client

Idempotency key was reused with different parameters.

422client

Request parameters or JSON body failed validation.

429client

Credential exceeded a short-window or per-minute rate limit.

5xxresponse

Unexpected ClassFlow failure. Retry safe reads and idempotent writes with backoff.

Rate limits

Limits are applied per credential at two windows:

120 requests per minute
30 requests per 10 seconds

Retry guidance

Retry 429 and transient 5xx responses with exponential backoff and jitter.
Do not retry validation or missing-scope failures until the request or credential changes.
Use the same idempotency key when retrying the same booking create or cancellation.
Set a retry ceiling and surface failures for operator review.