# Rate limits & usage

## The usage model

The Distribution Partner API meters on a **per-request** basis. The billable unit is a single availability/pricing request — not the number of properties, allocations, or slots returned.

| Request                                                 | Counted as usage                                                                                                |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `POST /search`                                          | Yes — one unit per request, regardless of how many `property_ids` it carries or how many allocations come back. |
| `POST /availability/check`                              | Yes — one unit per request (single-tuple gate trace).                                                           |
| `GET /properties`, `GET /properties/{public_id}`        | No — content reads are not metered.                                                                             |
| `POST /prebook`, `POST /book`                           | No — these are part of completing a booking, not pricing lookups.                                               |
| `GET /bookings/{public_id}`, cancellation-quote, cancel | No.                                                                                                             |

Two consequences worth designing around:

* **Batch your searches.** A single `POST /search` may carry up to 100 `property_ids` and is still one unit. Fanning the same stay window out as 100 separate single-property requests costs 100 units for the same result. Prefer one batched request.
* **Cache content freely.** Property catalogue reads are not metered, so build and refresh your local catalogue from `GET /properties` (with `updated_since` delta sync) as often as you need. See [Property content](/developer/property-content.md).

## Rate limiting

The API enforces a request rate ceiling per credential. When you exceed it, the service responds with:

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

```json
{
  "code": "rate_limited",
  "message": "request rate exceeded; retry after the indicated interval"
}
```

The body uses the standard [error envelope](/developer/errors.md) (`code` + `message`).

### Handling 429

1. **Honor `Retry-After`.** When the response carries a `Retry-After` header (seconds), wait at least that long before retrying.
2. **Back off exponentially.** When no `Retry-After` is present, retry with exponential backoff — for example 1s, 2s, 4s, 8s — capped at a sensible ceiling (e.g. 30s).
3. **Add jitter.** Randomize each delay by ±20% so concurrent workers do not retry in lockstep and re-trigger the limit.
4. **Cap retries.** Give up after a small number of attempts (e.g. 5) and surface the failure rather than retrying indefinitely.
5. **Smooth your own traffic.** Spread bulk searches over time and reuse batched `POST /search` calls rather than issuing many small ones in a burst.

### Safe to retry

`429` is always safe to retry — the request was rejected before any work was done. Booking writes (`/prebook`, `/book`) carry a mandatory `Idempotency-Key`, so retrying those after any transient error replays the original result instead of creating a duplicate. See [Idempotency](/developer/idempotency.md).

For the complete status-code table, see [Errors](/developer/errors.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://adrasis.gitbook.io/developer/rate-limits-and-usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.