Rate Limits

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

Limits

Limits are applied per project and per API key.

Rate Limit Headers

Every API response includes rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1646064000

What Happens When Rate Limited

When you exceed the rate limit, the API returns:

{
  "errors": [
    {
      "status": "429",
      "code": "RATE_LIMITED",
      "detail": "Too many requests"
    }
  ]
}

The response also includes a Retry-After header indicating how many seconds to wait before retrying.

Best Practices

1. Monitor Rate Limit Headers

Check X-RateLimit-Remaining before making requests. If it's low, slow down your request rate.

2. Implement Exponential Backoff

For 429 and 5xx responses, use exponential backoff:

1s → 2s → 4s → 8s → 16s

3. Batch Requests

Where possible, batch multiple operations into a single request rather than making many individual requests.

4. Cache Responses

Cache API responses when data doesn't change frequently. For example, plans and regions rarely change and can be cached.

5. Use Webhooks Instead of Polling

When webhooks are available, use them instead of polling the API for status changes.

6. Spread Requests Evenly

Instead of sending all requests at once, spread them evenly over time to avoid hitting burst limits.

Example: Handling Rate Limits

# Check remaining requests
curl -I https://api.fugoku.com/v1/servers \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

# Response headers:
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 12
# X-RateLimit-Reset: 1646064000

If X-RateLimit-Remaining is low, pause your requests until the reset time.