Understanding API Rate Limits and Error Codes
FuseIQ API error codes, rate limiting policies, and how to handle common HTTP errors.
The FuseIQ API uses standard HTTP status codes. This guide covers the codes you're most likely to encounter and how to handle them.
Rate Limits
FuseIQ applies rate limits per API key to ensure platform stability:
- Heartbeat API: 1 request per 5 seconds per agent
- REST API: 100 requests per minute per key
- WebSocket: 10 connections per workspace
- Simulation: 5 concurrent simulations per workspace
Rate limit headers are returned with every response. Monitor X-RateLimit-Remainingand Retry-After to stay within limits.
Common Error Codes
400 Bad Request
The request body is malformed or missing required fields. Check the error field in the response for details. Common cause: invalid heartbeat payload format.
401 Unauthorized
Your API key is missing, expired, or invalid. Generate a new key from Settings → API Keys.
403 Forbidden
Your key is valid but doesn't have permission for this action. Check role permissions or contact your workspace Director.
429 Too Many Requests
Rate limit exceeded. Check the Retry-After header and wait before sending another request. Consider implementing exponential backoff.
500 Internal Server Error
Something went wrong on our end. Retry after a few seconds. If the error persists, contact support@fuseiq.io.
Best Practices
- Implement exponential backoff with jitter for retry logic
- Store your API key in environment variables, never in code
- Monitor the Comms Hub for API health notifications
- Use the Analytics dashboard to track your API consumption trends