Getting Started

# Rate Limits

Understanding the request limits applied to the Mission Inbox API and how to handle them gracefully.

## Overview

Rate limits are enforced per API key on a rolling window basis. They protect the platform from abuse and ensure fair resource allocation across all customers. If you exceed the limit you will receive a `429 Too Many Requests` response until the window resets.

## Default Limits

Limits apply per product API key and are measured in requests per minute.

| Endpoint Group           | Limit        | Window   |
| ------------------------ | ------------ | -------- |
| All endpoints (default)  | 600 requests | 1 minute |
| Bulk operation endpoints | 30 requests  | 1 minute |

Higher limits are available on the Enterprise plan. Contact [support@missioninbox.com](mailto:support@missioninbox.com) if you need a limit increase.

## Response Headers

Every API response includes rate limit information in the following headers so you can monitor your usage and back off proactively.

Headers

```text
HTTP/1.1 200 OK
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Reset: 1740045660
```

| Header                | Description                                                     |
| --------------------- | --------------------------------------------------------------- |
| X-RateLimit-Limit     | Total requests allowed in the current window.                   |
| X-RateLimit-Remaining | Requests remaining before you are rate limited.                 |
| X-RateLimit-Reset     | Unix timestamp (seconds) when the window resets.                |
| Retry-After           | Seconds to wait before retrying. Present only on 429 responses. |

## 429 Too Many Requests

When you exceed the limit the API responds with `429` and a `Retry-After` header indicating how many seconds to wait.

Response

```json
HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error": "Too Many Requests"
}
```

Do not immediately retry on a `429`. Always honour the `Retry-After` value. Aggressive retry loops will extend your backoff period.

## Best Practices

Implement exponential backoff with jitter for any retry logic, and prefer bulk endpoints over loops of individual requests.

JavaScript

```javascript
async function requestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = parseInt(response.headers.get('Retry-After') ?? '5', 10);
    console.log(`Rate limited. Retrying in ${retryAfter}s...`);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
  }

  throw new Error('Max retries reached');
}
```

* Use bulk endpoints (e.g. POST /api/mailboxes/bulk-create) instead of looping single-create calls.
* Cache responses where possible — e.g. project and domain lists change infrequently.
* Monitor X-RateLimit-Remaining and slow down when it approaches zero.
* Avoid polling at high frequency; use background task SSE streams for long-running operations.

[PreviousErrors](https://doc.v4.missioninbox.com/sales/errors.md)[NextDomain Setup](https://doc.v4.missioninbox.com/sales/guides/domain-setup.md)
