Errors
The error envelope, types, and how to handle failures.
Every error response uses the same JSON envelope and an appropriate HTTP status:
{
"error": {
"type": "invalid_request",
"code": "missing_field",
"message": "first_name is required.",
"param": "first_name",
"request_id": "req_9f2b7c"
}
}typegroups the failure (see below). Branch on this.codeis a stable, machine-readable string. Safe to switch on.messageis human-readable. Do not parse it; it may change.paramnames the offending field, when applicable.request_ididentifies this exact request. Quote it when contacting support.
Types and statuses
type | HTTP | When |
|---|---|---|
invalid_request | 400 / 422 | Malformed or failing-validation input |
authentication | 401 | Missing or invalid API key |
permission | 403 | Missing scope, or target outside the key's locations |
not_found | 404 | The resource does not exist in your company |
conflict | 409 | The requested time is no longer available |
rate_limit | 429 | Too many requests, back off (see Rate limits) |
server | 500 / 503 | Something failed on our side, retry with backoff |
Handling conflicts on booking
POST /bookings and /bookings/{id}/reschedule return 409 slot_unavailable if the
slot was taken between your availability check and your write. Re-fetch
availability and offer the customer
another time, do not blindly retry.
Retrying safely
Retry only 429 and 5xx, with exponential backoff. For creates, always send an
Idempotency-Key so a retry cannot create a duplicate.