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

CodeStatusWhat to do
answers_invalid422Something the customer has to answer is missing or impossible. details.issues lists each one. Ask, then try again.
slot_unavailable409The time has gone. Ask for the free times again.
requires_action409The business takes payment or signed documents at booking. Send the customer to details.bookingUrl.
agents_off_for_business403The business does not take requests from AI assistants. Send the customer to details.bookingUrl.
bookings_paused403The business is not taking online bookings right now. The customer can contact it directly.
agent_writes_off403Booking without an API key is not open for this business. Send the customer to its booking page. The sandbox is always open.
business_not_found404No business is published at that slug.
rate_limited429Wait for the number of seconds in the Retry-After header, then try again.
api_key_invalid401The key is mistyped, revoked or expired.
scope_missing403The key is not allowed to do that. details.scope names the scope it needs.
internal_error500Something went wrong on our side. Quote the requestId when you report it.

Rate limits

CallerReads a minuteWrites a minute
Without a key, one caller to one business12010
Without a key, every caller to one business together60060
With a key, per key30060

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-Id is on every answer. Quote it when you report a problem.

  • Retry-After is on a 429 when waiting helps.

  • Idempotent-Replayed: true marks an answer given again for a repeated Idempotency-Key.