> ## 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 Limits

> Understand Orbit API rate limits per endpoint and how to handle 429 errors

# Rate Limits

Orbit enforces rate limits to ensure platform stability and fair usage. Limits are applied per API key at the endpoint level, and the same limits apply to every account. If your integration needs more throughput, we can raise a limit with a per-organization override — there is no separate plan tier to upgrade to. See [Requesting Higher Limits](#requesting-higher-limits).

## Overview

Every API response includes rate limit headers:

| Header                  | Description                                    |
| ----------------------- | ---------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | Requests remaining in the current window       |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets          |

When you exceed a rate limit, Orbit returns `429 Too Many Requests` with the `RATE_LIMITED` error code.

```json theme={null}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry in 12 seconds.",
    "status": 429,
    "retry_after": 12
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-08T12:00:00Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
  }
}
```

***

## Limits by Endpoint

### Messaging

| Endpoint                            | Limit    |
| ----------------------------------- | -------- |
| `POST /api/v1/messages/sms`         | 100/min  |
| `POST /api/v1/messages/whatsapp`    | 80/min   |
| `POST /api/v1/messages/email`       | 200/min  |
| `POST /api/v1/messages/rcs`         | 50/min   |
| `POST /api/v1/messages/viber`       | 50/min   |
| `POST /api/v1/messages/messenger`   | 80/min   |
| `POST /api/v1/messages/instagram`   | 200/hour |
| `POST /api/v1/messages/line`        | 80/min   |
| `POST /api/v1/messages/telegram`    | 80/min   |
| `POST /api/v1/messages/kakao`       | 80/min   |
| `POST /api/v1/messages/zalo`        | 80/min   |
| `POST /api/v1/messages/wechat`      | 80/min   |
| `POST /api/v1/messages/group` (MMS) | 30/min   |
| `POST /api/v1/messages/fax`         | 20/min   |
| `GET /api/v1/messages`              | 120/min  |
| `GET /api/v1/messages/{id}`         | 120/min  |

<Note>
  These per-channel send limits are the defaults that apply to every account. If your SMS (or any other channel) volume needs more headroom, we can raise the limit for your organization with a per-organization override — see [Requesting Higher Limits](#requesting-higher-limits).
</Note>

### Voice

| Endpoint                               | Limit   |
| -------------------------------------- | ------- |
| `POST /api/v1/voice/calls`             | 60/min  |
| `GET /api/v1/voice/calls`              | 120/min |
| `POST /api/v1/voice/calls/{id}/hangup` | 60/min  |

### Agents

| Endpoint                        | Limit  |
| ------------------------------- | ------ |
| `POST /api/v1/agents/{id}/chat` | 20/min |
| `POST /api/v1/agents`           | 20/min |
| `GET /api/v1/agents`            | 60/min |

### Numbers

| Endpoint                           | Limit   |
| ---------------------------------- | ------- |
| `GET /api/v1/numbers/available`    | 60/min  |
| `POST /api/v1/numbers/purchase`    | 5/min   |
| `POST /api/v1/numbers/bulk-lookup` | 5/min   |
| `GET /api/v1/numbers`              | 120/min |

### Contacts & Campaigns

| Endpoint                 | Limit   |
| ------------------------ | ------- |
| `POST /api/v1/contacts`  | 60/min  |
| `GET /api/v1/contacts`   | 120/min |
| `POST /api/v1/campaigns` | 60/min  |

### Billing & Webhooks

| Endpoint                | Limit   |
| ----------------------- | ------- |
| `GET /api/v1/billing/*` | 120/min |
| `POST /api/v1/webhooks` | 20/min  |
| `GET /api/v1/webhooks`  | 60/min  |

***

## Handling Rate Limits

### Best Practices

1. **Check headers proactively.** Monitor `X-RateLimit-Remaining` and slow down before hitting zero.
2. **Implement exponential backoff.** When receiving a `429`, wait `retry_after` seconds, then retry with increasing delays.
3. **Queue and batch.** For high-volume sends, queue messages and send in controlled batches.
4. **Use webhooks instead of polling.** Subscribe to status webhooks rather than polling `GET /api/v1/messages/{id}`.

### Retry Example

```javascript theme={null}
async function sendWithRetry(params, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await orbit.messages.send(params)
    } catch (error) {
      if (error.status === 429 && attempt < maxRetries - 1) {
        const retryAfter = error.retry_after ?? Math.pow(2, attempt)
        await new Promise(r => setTimeout(r, retryAfter * 1000))
        continue
      }
      throw error
    }
  }
}
```

```python theme={null}
import time

def send_with_retry(params, max_retries=3):
    for attempt in range(max_retries):
        try:
            return orbit.messages.send(**params)
        except OrbitError as e:
            if e.status == 429 and attempt < max_retries - 1:
                retry_after = e.retry_after or 2 ** attempt
                time.sleep(retry_after)
                continue
            raise
```

***

## Global Per-Second Limit

In addition to the per-minute endpoint limits above, a single global limiter caps **every** API key at **50 requests per second** as a platform safety net. This ceiling is applied uniformly to all callers regardless of plan — it is not a separate per-plan tier and there is no burst queue.

Requests beyond 50 req/sec receive `429 Too Many Requests` **immediately**; they are not queued or delayed before rejection. In practice the per-minute endpoint limits above are the binding constraint for normal usage, so this global ceiling is rarely the limit you hit first. Apply the same exponential-backoff handling described above when you do.

***

## Requesting Higher Limits

The default limits above apply to every account. If your integration needs more throughput, we can raise a specific limit with a per-organization override — there is no separate plan to upgrade to. Email [support@devotel.io](mailto:support@devotel.io) with the endpoints you need raised and the sustained rate you expect.

<Tip>
  If you consistently hit rate limits, first optimize your integration to use webhooks and batching. If you still need more headroom, request a per-organization limit increase.
</Tip>