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

# Rate limits and retries

> How the TruAgents public API signals rate limiting plus the recommended retry policy for network errors, server failures, and 429 responses.

The TruAgents public API responds with `429 Too Many Requests` and a `Retry-After` header when a client exceeds a rate limit. Limits are applied per `client_id`: a single credential authorized across multiple organizations shares one budget. Implement backoff in your client so a hot loop does not amplify the pause.

Graceful 429 handling on `POST /oauth/token` — the token endpoint — requires the first-party SDK at version `truagents >= 0.2.0`; older releases surface the 429 as a generic authentication error without honouring `Retry-After`.

## Retry policy

The first-party [`truagents` Python SDK](/sdks/python) implements the recommended policy — mirror it in any hand-rolled client:

| Response                    | Retry? | How                                                                                                                                          |
| --------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Network / transport failure | Yes    | Exponential backoff, small attempt cap (default: 3).                                                                                         |
| `5xx` server error          | Yes    | Same exponential backoff.                                                                                                                    |
| `429 Too Many Requests`     | Yes    | Sleep for the duration given in the `Retry-After` header, then retry. Cap the wait at 60 s.                                                  |
| `400` bad request           | No     | Fix the request.                                                                                                                             |
| `401` unauthorized          | No     | Refresh the token — see [Authentication → Refresh the access token](/developers/authentication#step-3-refresh-the-access-token).             |
| `403` forbidden             | No     | Fix the credential scope or requested organization — see [Unsubscribe API → Error responses](/integrations/unsubscribe-api#error-responses). |
| `404` not found             | No     | The resource does not exist.                                                                                                                 |

Idempotent reads (any `GET`) are always safe to retry. Writes (`POST`) inherit safety from the specific endpoint — see the API page for guidance.

## Related pages

* [Authentication → Rate limits](/developers/authentication#rate-limits) — the token-endpoint and API rate-limit contract.
* [Unsubscribe API → Error responses](/integrations/unsubscribe-api#error-responses) — per-endpoint status codes.
* [Python SDK](/sdks/python) — `RetryPolicy` implementation reference.
* [Errors and status codes](/developers/errors-and-status-codes) — response envelope and where to find per-API detail.