Rate Limits

BlueNexus applies rate limiting to protect the platform and ensure fair usage.

Limits by Endpoint

Endpoint	Limit	Window
Global default	100 requests	1 minute
POST /mcp	30 requests	1 minute
POST /v1/agents/:id/chat/completions	30 requests	1 minute
POST /v1/chat/completions	30 requests	1 minute
POST /v1/auth/authenticate	10 requests	1 minute
POST /v1/auth/token	10 requests	1 minute
POST /v1/auth/revoke	10 requests	1 minute
POST /v1/auth/register (DCR)	5 requests	1 minute

Rate Limit Response

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

{
  "error": "TooManyRequestsError",
  "message": "Rate limit exceeded",
  "statusCode": 429
}

Credit Guard

In addition to rate limits, certain endpoints require a positive credit balance:

Endpoint	Guard
POST /mcp	Credit balance must be > 0
POST /v1/agents/:id/chat/completions	Credit balance must be > 0
POST /v1/chat/completions	Credit balance must be > 0

If credits are exhausted, the API returns 402 Payment Required:

{
  "error": "CreditsExhaustedError",
  "message": "Insufficient credit balance",
  "statusCode": 402
}

Best Practices

1. Implement exponential backoff — On 429 responses, wait and retry with increasing delays.
2. Batch where possible — Combine multiple tasks into a single use-agent call instead of making separate calls.
3. Cache responses — Cache provider listings and tool definitions that don't change frequently.
4. Monitor usage — Track the X-Credits-Consumed and X-Credits-Remaining headers to stay aware of your balance.