Core concepts

Errors and rate limits

Handle failures by status code, then use response detail for the exact cause.

Error shape

403 / application/json

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

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.

503server

Request protection is temporarily unavailable. Retry after the response delay.

5xxresponse

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

Rate limits

Limits are applied per credential at per-minute and short-burst windows:

Reads: 120 requests per minute and 30 per 10 seconds
Writes: 30 requests per minute and 10 per 10 seconds

Authenticated responses include X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. The reset value is the number of seconds remaining in the current minute window. Burst values are included in X-RateLimit-Burst-Limit and X-RateLimit-Burst-Remaining.

Retry guidance

Retry 429 and transient 5xx responses with exponential backoff and jitter.
Respect Retry-After on 429 and 503; ClassFlow intentionally declines Partner API traffic if rate protection is unavailable.
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.