Developer docs
Errors, rate limits and retries
Response format, error codes, the rate limit and safe retries.
On this page (4)
Response format
Every response is JSON with the same envelope.
Success
{ "status": true, "message": "OK", "data": { } }
Error
{
"status": false,
"message": "The selected staff member is not available at this time.",
"error": { "code": "slot_unavailable" }
}
Validation errors also include an errors object keyed by field.
Error codes
| HTTP | error.code |
Meaning |
|---|---|---|
| 401 | unauthorized |
The key is missing, wrong or deleted. |
| 404 | not_found |
The booking does not exist for this business. |
| 409 | slot_unavailable |
The time is no longer free. Fetch availability again and pick another slot. |
| 409 | invalid_state |
The booking cannot be cancelled from its current status. |
| 409 | idempotency_conflict |
The Idempotency-Key was already used with different booking details. |
| 422 | validation_failed |
A field is missing or invalid. See errors. |
| 429 | (none) | Rate limit reached. |
| 500 | server_error |
Something went wrong on our side. Safe to retry with the same Idempotency-Key. |
Rate limit
Each API key may make 120 requests per minute. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining. A 429 response includes Retry-After in seconds.
Safe retries with idempotency keys
Networks fail. To retry POST /bookings without risking a double booking, send an Idempotency-Key header (any string up to 255 characters, for example your own order ID).
- Same key, same details: you get the original booking back with HTTP
200instead of201. - Same key, different details:
409 idempotency_conflict.
Keys are scoped to the business, so two businesses can use the same value.