Skip to content

Errors and rate limits

The Bookline API's error format, what each code means, the request limits and when to retry.

Every error has the same body: a stable code, meant for your code, and a readable message that explains the cause.

{ "error": { "code": "range_too_large", "message": "at most 31 days for granularity=day" } }

available_from appears only on a not_found caused by agents that moved accounts (see the data rules).

Status Code When What to do
400 invalid_query A parameter is missing, malformed or not accepted by the endpoint; a cursor from another query; or a POST without Idempotency-Key Fix the request; the message names the parameter
400 range_too_large Window over 31 days (day) or 92 days (total) on metrics, or over 31 days on calls, chats or bookings Split the window
400 industry_ambiguous Customer has restaurant and hotel agents Pass industry
400 customer_ambiguous Key reads several customers Pass customer_id
400 granularity_not_supported granularity=day on survey-ratings Use total
401 invalid_api_key Missing, unknown, revoked or expired key Check the apikey header
403 insufficient_scope Customer or venue outside the key’s access, a route the key has no scope for, a whole-customer route called with a venue-restricted key, or a write the key’s owner may not make Check customer_id / venue_ids, the key’s scopes or its owner’s access; the message says which
404 venue_not_found A venue_ids entry is not the customer’s Use ids from GET /venues
404 not_found Resource not available for the customer’s industry, no data before available_from, or an id that is not your customer’s Change the endpoint, start the window at available_from or check the id
409 conflict A write the data does not allow (a duplicate contact, a knowledge base a venue still uses…), or an Idempotency-Key reused or still unresolved Read the message; see Writing data
412 precondition_failed The If-Match version is not the current one: the resource changed since you read it Read it again and resend with the new ETag
413 validation_failed The body is over 865,536 bytes Send a smaller body
422 validation_failed The body has a field the route does not take, or a value outside its rules Fix the field the message names
428 precondition_required A PATCH or DELETE without If-Match Send the ETag of the resource as If-Match
429 rate_limited Over the key’s limit: 60 reads, 10 writes or 30 personal-data requests per minute Wait Retry-After seconds
502 upstream_error Internal error Retry later
503 upstream_busy Too many requests at once Retry after a few seconds
504 upstream_timeout The request took too long Retry with a shorter window

A key’s scopes cannot change: if an insufficient_scope comes from a missing scope, create a new key that has it. See Keys and scopes.

Every key has these limits per minute. Every request counts, failed ones included.

Requests Limit per key
Reads (GET) 60 per minute
Writes (POST, PATCH, DELETE) 10 per minute
Personal data, also 30 per minute

The personal-data limit applies on top of the other two to the routes that return personal data: calls, chats, bookings, contacts, team members, billing accounts and survey ratings, and to the writes that answer a contact or a team member. The X-RateLimit-* headers reflect the tightest limit that applies.

Header When What it tells you
X-RateLimit-Limit Successful responses Requests allowed in the window
X-RateLimit-Remaining Successful responses Requests left in the window
X-RateLimit-Reset Successful responses Seconds until the window resets
Retry-After 429 rate_limited Seconds to wait before calling again
X-Request-Id Every response The request’s identifier
ETag Detail reads and writes of resources you can change The version to send as If-Match
Idempotent-Replayed A POST resent with the same Idempotency-Key true: the answer is the first request’s, nothing was created twice
  • 4xx (except 429): don’t retry the same request. The problem is in the request or the key, and it will fail the same way again: fix it using the table.
  • 429: wait Retry-After seconds and try again. To stay under the limit, watch X-RateLimit-Remaining and wait X-RateLimit-Reset seconds when it reaches zero.
  • 502 and 503: retry after a few seconds, leaving more time between each attempt.
  • 504: the request took too long; for metrics, retry with a shorter window.
  • 412: read the resource again and resend the write with the new ETag.
  • A write that ends in 502, 503 or 504 may have been applied. Read the resource (or list it, for a create) before sending it again; a create sent again with the same Idempotency-Key is a 409, never a second create. See Writing data.

Retries count towards the limit too, so don’t retry in a loop without waiting.