Errors and rate limits
The Bookline API's error format, what each code means, the request limits and when to retry.
Error format
Section titled “Error format”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).
Error codes
Section titled “Error codes”| 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.
Rate limit
Section titled “Rate limit”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.
Response headers
Section titled “Response headers”| 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 |
When to retry
Section titled “When to retry”- 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-Afterseconds and try again. To stay under the limit, watchX-RateLimit-Remainingand waitX-RateLimit-Resetseconds 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-Keyis a 409, never a second create. See Writing data.
Retries count towards the limit too, so don’t retry in a loop without waiting.
