Developer docs menu
Reference
Errors and limits
What a refusal looks like, the codes worth handling, and the rate limits.
A refusal
{
"error": "That time has just been taken. Ask for the free times again.",
"code": "slot_unavailable",
"requestId": "req_…"
}Test code, not the sentence: the wording can change. The codes each operation can answer with are listed, by status, in the API reference.
Codes worth handling
| Code | Status | What to do |
|---|---|---|
| answers_invalid | 422 | Something the customer has to answer is missing or impossible. details.issues lists each one. Ask, then try again. |
| slot_unavailable | 409 | The time has gone. Ask for the free times again. |
| requires_action | 409 | The business takes payment or signed documents at booking. Send the customer to details.bookingUrl. |
| agents_off_for_business | 403 | The business does not take requests from AI assistants. Send the customer to details.bookingUrl. |
| bookings_paused | 403 | The business is not taking online bookings right now. The customer can contact it directly. |
| agent_writes_off | 403 | Booking without an API key is not open for this business. Send the customer to its booking page. The sandbox is always open. |
| business_not_found | 404 | No business is published at that slug. |
| rate_limited | 429 | Wait for the number of seconds in the Retry-After header, then try again. |
| api_key_invalid | 401 | The key is mistyped, revoked or expired. |
| scope_missing | 403 | The key is not allowed to do that. details.scope names the scope it needs. |
| internal_error | 500 | Something went wrong on our side. Quote the requestId when you report it. |
Rate limits
| Caller | Reads a minute | Writes a minute |
|---|---|---|
| Without a key, one caller to one business | 120 | 10 |
| Without a key, every caller to one business together | 600 | 60 |
| With a key, per key | 300 | 60 |
A quote counts as a read: it saves nothing. A hold and a booking are writes. Requests through this API are counted apart from the business’s own booking form, so they can never use up the allowance its customers book with.
Every answer
X-Request-Idis on every answer. Quote it when you report a problem.Retry-Afteris on a429when waiting helps.Idempotent-Replayed: truemarks an answer given again for a repeatedIdempotency-Key.
Still have questions? Contact support