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

# Rate Limits

> Request limits, throttling behavior, and how to handle 429 responses.

All API keys are rate-limited to protect the platform and ensure fair usage across workspaces.

## Default Limits

| Limit               | Value                                |
| ------------------- | ------------------------------------ |
| Requests per minute | **1,000** per API key                |
| Max configurable    | **10,000** per API key               |
| Burst allowance     | Up to 50 requests in a single second |

## Response Headers

Every response includes rate limit headers:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1711180800
```

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

## Exceeding the Limit

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "retry_after": 12
  }
}
```

The `Retry-After` header indicates how many seconds to wait before retrying.

## Best Practices

<CardGroup cols={2}>
  <Card title="Use bulk operations" icon="layer-group">
    Prefer `records.bulk_create` and `lists.bulk_add_entry` over individual calls when creating multiple items.
  </Card>

  <Card title="Cache reads" icon="database">
    Cache `objects.list` and `views.list` responses — schemas change infrequently.
  </Card>

  <Card title="Respect Retry-After" icon="clock">
    Always honor the `Retry-After` header. Exponential backoff is recommended.
  </Card>

  <Card title="Request higher limits" icon="arrow-up">
    Contact support to increase your per-key limit up to 10,000 requests/minute.
  </Card>
</CardGroup>

## Configuring Limits

Workspace owners can adjust per-key rate limits:

1. Go to **Settings** > **Developers** > **API Keys**
2. Click the key you want to modify
3. Set the **Rate Limit** field (100 to 10,000)
4. Save