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

# RATE_LIMITED

> The request exceeded the rate limit for your API key or organization, so it was rejected with HTTP 429.

## What this error means

`RATE_LIMITED` is returned with HTTP status **429** when your integration sends
more requests per window than the current rate limit allows. The request is
rejected before any work is done; nothing is sent and no credits are deducted.
The response also carries a `Retry-After` header holding the same number of
seconds as the body.

Every response for this error carries this page's address in `meta.docs_url`:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry in 12 seconds.",
    "status": 429,
    "retry_after": 12
  },
  "meta": {
    "request_id": "req_01J9ZKQ3V8",
    "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
  }
}
```

## Cause

The limit is shared per API key, so anything that concentrates traffic on one
key trips it. The most common causes are:

| Situation | Why it trips the limit |
| - | - |
| A batch job firing sends in a tight loop | Requests arrive faster than the per-window budget |
| Several integrations sharing one API key | Independent services consume a single quota |
| Retrying failures immediately in a loop | Retries multiply the original load instead of replacing it |
| Polling a read endpoint every second | List and read calls count against the same limit as writes |

## How to fix it

1. **Honor `retry_after` first.** The envelope's `retry_after` field (mirrored in
   the `Retry-After` header) is the number of seconds to wait before reissuing
   the request. Sleep for that long instead of retrying immediately; an
   immediate retry lands in the same window and is rejected again.
2. **Fall back to exponential backoff when the field is absent.** Other
   transient errors do not always carry a wait time; start at one second,
   double on each attempt, and add jitter so concurrent clients do not
   re-synchronize into a new burst.
3. **Queue and pace batch work.** Spread a bulk send over the window instead of
   firing it all at once; a steady drip stays under the limit where a burst
   does not.
4. **Use one key per integration.** Separate keys keep separate workloads from
   consuming each other's quota, and make it obvious which integration is the
   loud one.

Once the window has passed, retry the original request unchanged; a 429 does
not mean the payload was wrong.

## Related

* [Error Code Reference](https://docs.orbit.devotel.io/reference/error-codes.md#from-a-code-to-a-runbook) —
  `RATE_LIMITED` sits in the transient retry class: honor the returned wait
  time, otherwise back off exponentially.
* [Rate limits and cool-downs](https://docs.orbit.devotel.io/troubleshooting/rate-limits.md) — the full runbook
  for limits, headers, and cool-down behavior.
* [Error Handling Examples](https://docs.orbit.devotel.io/guides/error-handling-examples.md) — response-envelope
  handling patterns in code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.