# rate_limited

- HTTP status: 429
- Retry: After Retry-After
- Execution: not started
- Admin needed: no

**Rate limit exceeded.** Requests are limited per key and per workspace, separately for test and live mode, in three classes: read, write and dial. Requests that end before they reach an operation (an unknown path or method, a body that is refused, a missing or invalid key, a workspace without API access) are also counted per client IP address: 300 a minute; once that is spent, every request from the address answers this error (`details.limit_class` `read`) until the window resets. `RateLimit-*` headers on every response show the budget that applied to it.

## What it means

The API returns HTTP 429 with `error.code` set to `rate_limited`. The default message is: "Too many requests. Retry after the number of seconds in the Retry-After header."

## Common causes

- A burst of requests above the class limit.
- Several keys in the same workspace sharing the workspace limit.
- More than 300 requests a minute from one IP address that failed before reaching an operation (for example a client sending an invalid key in a loop).

## How to identify it

Check the response status (`429`) and `error.code` (`rate_limited`). Branch on `error.code`, not on the message text: messages can be reworded, codes do not change within v1. Log `error.request_id` (also sent as the `X-Request-Id` header) so support can find the request.

## How to fix it

- Wait `Retry-After` seconds. Spread requests out and back off exponentially.
- Fix requests that fail authentication or routing: they count against the address.

## Retry guidance

Wait for the number of seconds in the `Retry-After` response header, then retry.

## Did anything happen?

This request was refused before any call was placed and before anything was charged.

## Idempotency

Nothing was done. Retry after the wait (with the same Idempotency-Key if you sent one).

## Who can fix it

The developer who sends the request can fix it; no administrator action is normally needed.

## When to contact support

If your steady workload needs higher limits, write to [support@relationsai.com](mailto:support@relationsai.com). See [Support](/resources/support) for what to include (the `request_id`, the time in UTC, the operation, and whether you used a test or live key) and what never to send (API keys, Authorization headers, webhook signing secrets, recording links, transcripts or customer data).

## Example error response

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after the number of seconds in the Retry-After header.",
    "details": {
      "limit_class": "write"
    },
    "request_id": "req_uppzyvuxkt7wv43lgedhqsyb",
    "retry": "after",
    "doc_url": "https://docs.relationsai.com/errors/rate_limited"
  }
}
```

See all codes in the [error-code reference](/fundamentals/error-codes).