Rate Limits

The FAOS API enforces rate limits to ensure fair usage and platform stability.

Default Limits

Tier	Requests/Minute	Burst
Free	20	5
Starter	60	15
Business	300	50
Enterprise	Custom	Custom

Per-Endpoint Limits

Some endpoints have specific rate limits that override the default:

Endpoint	Limit	Window
POST /api/v1/registry/invoke/{id}	60 req	1 min
POST /api/v1/agents/deploy	10 req	1 min
POST /api/v1/shortcuts/resolve	120 req	1 min
GET /api/v1/registry/discover	120 req	1 min
POST /api/v1/marketplace/publish	5 req	1 min

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

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

Handling 429 Responses

When you exceed the rate limit, the API returns 429 Too Many Requests:

{
  "type": "rate_limit_exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded 60 requests per minute. Retry after 15 seconds."
}

The response includes a Retry-After header indicating how many seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 15

SDK Automatic Retry

Both the Python and TypeScript SDKs automatically handle 429 responses with exponential backoff:

from faos import FaosClient

# SDK automatically retries on 429 with backoff
client = FaosClient(api_key="faos_sk_live_...")
response = client.agents.invoke("credit-risk-analyst", {"query": "..."})

Best Practices

• Use exponential backoff when retrying rate-limited requests
• Cache responses when possible to reduce API calls
• Batch operations instead of making many individual requests
• Monitor X-RateLimit-Remaining to anticipate limits
• Contact support if you need higher limits for production workloads