> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits and backoff

> Read quota headers, honor Retry-After, and control concurrency without relying on an undocumented fixed limit.

Rate limiting is applied to the API key. The public contract does not define one global numeric quota that clients should hard-code. Read the response headers for the effective policy and current availability.

## Response headers

| Header             | Meaning                                                              |
| ------------------ | -------------------------------------------------------------------- |
| `RateLimit-Policy` | Effective request quota policy expressed as an HTTP structured field |
| `RateLimit`        | Current quota availability and effective window                      |
| `Retry-After`      | Seconds to wait when request-rate admission is rejected              |
| `X-Request-ID`     | Correlation identifier for the response                              |

A rate-limited response uses HTTP `429` and `RATE_LIMIT_EXCEEDED`.

## Handling flow

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    A[Receive response] --> B{Status 429?}
    B -- No --> C[Continue normal processing]
    B -- Yes --> D[Read Retry-After]
    D --> E[Pause new attempts for that key]
    E --> F[Apply jitter and retry budget]
    F --> G[Retry with new X-Request-ID]
```

## Client recommendations

* Do not hard-code a quota that is not defined by your effective response headers.
* Limit concurrent requests per API key.
* Share rate-limit state across workers that use the same key.
* Add random jitter to avoid synchronized retries.
* Stop retries when the operation's budget is exhausted.
* Separate retry handling from business validation queues.
* Do not rotate keys merely to bypass rate limits.

## Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 429 Too Many Requests
RateLimit-Policy: ...
RateLimit: ...
Retry-After: 60
X-Request-ID: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4
```

Wait at least 60 seconds before another rate-admitted attempt for the affected key, then apply the client's retry budget.

<Note>
  The OpenAPI contract specifies the header semantics but not customer-specific or dynamically effective numeric quotas. Treat live response headers as authoritative.
</Note>