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

# Rate limits

> How Metal rate limits API requests and how to handle 429 responses.

To keep the platform fast and fair for everyone, the Metal API enforces rate limits. Limits are applied per organization and depend on your plan.

## What to expect

When you exceed your rate limit, the API responds with:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 429 Too Many Requests
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "error": "rate limit exceeded" }
```

Requests are throttled at the organization level, so all keys belonging to your organization share the same budget.

## Handling 429 responses

Treat `429` as a signal to slow down, not as a failure. Retry the request after a short delay, increasing the delay on repeated `429`s (exponential backoff).

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import time
import requests

def get_with_backoff(url, headers, max_retries=5):
    delay = 1
    for _ in range(max_retries):
        res = requests.get(url, headers=headers)
        if res.status_code != 429:
            return res
        time.sleep(delay)
        delay *= 2  # exponential backoff
    return res
```

## Best practices

<CardGroup cols={2}>
  <Card title="Back off exponentially" icon="hourglass-half">
    Double the wait time after each consecutive `429` to let the limit recover.
  </Card>

  <Card title="Add jitter" icon="shuffle">
    Randomize backoff slightly so retries from multiple workers don't align.
  </Card>

  <Card title="Batch where possible" icon="layer-group">
    Use list-based bulk operations instead of many single-record calls.
  </Card>

  <Card title="Cache reads" icon="database">
    Avoid re-fetching data that rarely changes within a short window.
  </Card>
</CardGroup>

<Info>
  If your integration consistently needs higher throughput, contact [support@metal.ai](mailto:support@metal.ai) to discuss limits for your plan.
</Info>


## Related topics

- [MCP tools reference](/mcp/tools-reference.md)
- [API reference](/api-reference/introduction.md)
- [Errors](/guides/errors.md)
- [Sync your data](/guides/sync-data.md)
- [Enrich companies](/guides/enrich-companies.md)