Rate limits and idempotency

Rate limits

Endpoints	Limit
Endpoints under `/car-rental/`, `/fleets/`, `/contacts/`, `/invoices/`, `/payment-gateways/`, `/sheets/`, `/files/` and `/inventory/`	1,000 requests per minute per user, shared
`GET` and `POST /car-rental/reservations/additional-charges`	60 requests per minute per user, shared by `GET` and `POST`
`POST /car-rental/reservations/{reservation_id}/quote`	30 requests per minute per user

The 1,000 requests per minute are one budget per user, shared by all of these endpoints and by every system that uses the same user token.
The two lower limits apply on top of it.
Give each external system its own user, so one system cannot use up the budget of another.

Responses from these endpoints include X-RateLimit-Limit and X-RateLimit-Remaining.
Over the limit, the API returns HTTP 429 with a Retry-After header in seconds (see the example in Errors).
Wait that long before you retry, and back off further if 429s repeat.

To stay under the limit, use updated_since instead of re-reading lists (see Filtering and incremental sync), and cache data that rarely changes, such as locations, rates and additional charges.

Idempotency

A network error can leave you unsure whether a reservation was created or updated.
Send an Idempotency-Key header to make the retry safe on these endpoints:

POST /car-rental/reservations/confirm

POST /car-rental/reservations/{reservation_id}/update

Other endpoints ignore the header.

The other booking fields are left out here; see POST /car-rental/reservations/confirm for the full request.

Use a new key, for example a UUID, for each operation, and reuse it only to retry that same request.
HQ keeps each key for up to 24 hours, per account and per endpoint path.
Cancelling a reservation through POST /car-rental/reservations/{reservation_id}/cancelled clears every stored key of the account, so a retry sent after that is processed as a new request: read the reservation before retrying.

In these responses every value under errors is an array, so check whether errors.idempotency_value is empty, not whether it exists.

What your retry with the same key returns	What it means and what to do
On `confirm`, HTTP 422, `errors.idempotency_key` is `["The specified key already exists"]` and `errors.idempotency_value` holds an ID, for example `["1234"]`	The reservation was created. Fetch reservation `1234` instead of booking again.
HTTP 422, `errors.idempotency_key` is `["Lock timeout"]`, or `["The specified key already exists"]` with an empty `errors.idempotency_value` `[]`	The first request may still be running, may have failed, or may have succeeded. Wait a few seconds and read the reservation, for example the reservations list filtered by the customer's email, before you retry with a new key.
The normal response of the endpoint	The first request never reached HQ, or failed with an HTTP error status, which released the key; the retry was processed normally.

If confirm fails with a 5xx error, the reservation may still have been created even though the key was released, so look it up before you retry.

A successful confirm also returns the new reservation ID in the X-Idempotent-Id response header.

Rate limits#

Idempotency#

Rate limits

Idempotency