Rate limits

Limits keep the API fast for every hotel. They are generous for normal use: a booking channel making a handful of calls per booking won't come near them.

The limitsCopy Anchor Link

Each app connection has its own token, so the limit applies per hotel, not per app.

Going overCopy Anchor Link

The API answers 429 Too Many Requests with a Retry-After header: the seconds to wait.

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{"detail": "Too many calls for this key (at most 120 a minute). Wait 12 seconds and try again."}

The OAuth endpoints answer the same way, in the OAuth shape:

{ "error": "slow_down", "error_description": "Too many requests. Wait 12 seconds." }

Wait for Retry-After and try again. A request refused with 429 did nothing, so it is safe to resend.

PausedCopy Anchor Link

If the partner API is paused, for one hotel or for everyone (during an incident, for example), calls answer 503 Service Unavailable with Retry-After: 600. Wait and try again; the status page says what's happening.

Staying insideCopy Anchor Link

• Use webhooks instead of polling. One webhook replaces thousands of "anything new?" calls. See Keep in sync.
• Cache what rarely changes. Room types, rate plans, extras and policies change seldom: fetch them once an hour, or when a booking refers to something you don't know.
• Search once per guest search. One offer.search call returns every room type and rate plan for the dates.
• Spread background work. A nightly check over many hotels doesn't need to start at midnight for all of them.
• Back off. On 429, wait Retry-After; on 5xx, wait 1, 2, 4, 8... seconds.

Need more? Write to contact@chatbeds.app with what you're building and the numbers you expect.