Guides

Errors and limits

Every failure has the same shape and a stable code. Branch on the code, never on the prose.

{
  "error": {
    "code": "forbidden",
    "message": "This key does not carry the \"customers:read\" scope. Its scopes are: catalog:read, availability:read."
  }
}

Codes are a closed set and will not change meaning; messages are free to improve, so an integration that matches on wording will break and one that matches on error.code will not. A invalid_request also carries details naming the field at fault, and a refused write carries the exact reason — see below.

Codes#

Why a write was refused#

Creating, moving or cancelling a booking can be refused for many reasons, and they do not all want the same response. The status says what kind of refusal it is; details.reason names the exact case; details.forceable says whether resending with force: true is an answer. Nothing is written on any of them.

{
  "error": {
    "code": "conflict",
    "message": "That time cannot be booked: Already booked at this time (appointment #1100)",
    "details": {
      "reason": "staff_busy",
      "forceable": true,
      "parameter": "startsAt",
      "warnings": [
        {
          "kind": "staff_busy",
          "message": "Already booked at this time (appointment #1100)",
          "conflictingAppointmentId": 1100
        }
      ]
    }
  },
  "sandbox": "Sandbox data. These are fixtures for a made-up business: nothing here is a real booking, and nothing you send is stored."
}

force: true is the owner’s own “Book anyway”: it overrides a busy time, a buffer, working hours, a block, a class, a connected calendar, a full group or a start in the past. It never overrides whose record something is, a one-to-one double-booking or a taken room. When a time has several problems, details.warnings lists them all.

Rate limits#

Two limits apply to every key, and they answer different questions.

• 120 requests per minute. Burst control — it stops a runaway loop spending a whole day’s budget before anyone can revoke the key. Exceeding it returns rate_limited.
• A daily quota per key, set by the plan and reported by GET /me. It resets at 00:00 UTC. Exceeding it returns quota_exceeded.

The quota is counted per key, not per business, so a key you are debugging cannot starve the automation already running the business — and a key that misbehaves can be identified and revoked on its own.

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9997
Retry-After: 43200

The first two are on successes as well as failures, so a client can slow itself down before it is refused rather than discovering the limit by hitting it. Retry-After is in seconds and appears only on a 429.

Paging#

GET /customers takes limit and offset; GET /bookings is bounded by its date range instead. The default page is 50 and the maximum is 100; a larger limit is capped rather than rejected, because refusing teaches an integration nothing it can act on.

{
  "data": [
    {
      "id": 12,
      "name": "Priya Menon"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

There is no total. hasMore is resolved by fetching one row more than the page, not by a second count query over the same predicate — so paging stays cheap however deep you go.

Retrying safely#

• GET requests are safe to retry. POST /bookings is not idempotent — a retry after a timeout can create a second booking, so read the range back before retrying a create.
• Cancelling an already-cancelled booking is refused rather than silently succeeding, so it is safe to call twice. Rescheduling to the time a booking already has answers changed: false and writes nothing, so it is safe to repeat too.
• Back off exponentially on 429 and internal_error. Do not retry 403, 404 or invalid_request unchanged.