Rate limits

To keep the platform fast and fair for everyone, the Metal API enforces rate limits.

What to expect

The default API budget is 1,500 requests per minute per authenticated principal — each API key, or each signed-in user. Keys do not share one organization-wide bucket: two keys can each use their own 1,500/minute window. When you exceed the limit, the API responds with 429 Too Many Requests and includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers (X-RateLimit-Reset is Unix epoch seconds):

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 1500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1789000042

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "retry_after": 42
}

The Metal MCP server enforces a separate per-user limit on tool calls. Limit errors there also include retry_after seconds. See MCP tools reference.

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 429s (exponential backoff).

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

Back off exponentially

Double the wait time after each consecutive 429 to let the limit recover.

Add jitter

Randomize backoff slightly so retries from multiple workers don’t align.

Batch where possible

Use list-based bulk operations instead of many single-record calls.

Cache reads

Avoid re-fetching data that rarely changes within a short window.

If your integration consistently needs higher throughput, contact support@metal.ai to discuss limits for your plan.

Core tasks

API essentials

What to expect

Handling 429 responses

Best practices

Back off exponentially

Add jitter

Batch where possible

Cache reads

​What to expect

​Handling 429 responses

​Best practices

Back off exponentially

Add jitter

Batch where possible

Cache reads

What to expect

Handling 429 responses

Best practices