Rate Limits and Error Handling

The Query endpoint is protected by multiple usage controls to ensure fair usage, maintain platform stability, and prevent excessive resource consumption.

Requests may be rejected when a project exceeds its configured request rate, token allowance, or available credit balance.

Rate Limits

Statement applies request-based rate limits to the Query endpoint.

When the allowed request rate is exceeded, the API returns a rate limit error.

Example Response

HTTP 429 Too Many Requests

{
  "detail": "Rate limit exceeded (5/m) for this endpoint"
}

This indicates that the project has exceeded the maximum number of requests allowed for the endpoint during the current rate limit window.

Token Limits

Projects may also be subject to token-based limits that restrict the number of tokens processed within a given time period.

When a token limit is exceeded, the API rejects the request before processing.

Example Response

HTTP 429 Too Many Requests

{
  "detail": "Token limit exceeded (1000/tpm)"
}

In this example, the project has exceeded its allocation of 1,000 tokens per minute.

Credit Limits

Projects must have sufficient credits available to process agent requests.

If a project's credit balance is exhausted, new queries cannot be executed until additional credits are added.

Example Response

HTTP 402 Payment Required

{
  "detail": "Credit limit exceeded for this project. Please top up to continue."
}

Internal Errors

In rare cases, an unexpected error may occur while processing a query.

These errors can result from temporary service disruptions, upstream provider failures, unavailable integrations, or other unforeseen conditions.

Example Response

HTTP 500 Internal Server Error

{
  "detail": "Internal agent query error"
}

When a 500 error occurs, retrying the request after a short delay is recommended.

Error Response Format

All error responses follow a consistent structure:

{
  "detail": "Human-readable error message"
}

The detail field contains a description of the reason the request could not be processed.

Common Error Codes

Best Practices

To minimize errors and maximize reliability:

• Monitor token consumption using the Token Usage endpoint.
• Avoid sending unnecessarily large conversation histories.
• Implement retry logic with exponential backoff for 429 and 500 responses.
• Validate request payloads before sending them.
• Monitor project credit balances to prevent service interruptions.
• Use agent_scope when appropriate to reduce unnecessary routing and processing.

Notes

• Limits are enforced at the project level and are scoped to the authenticated API key.
• Rate limits, token limits, and credit limits may vary depending on your plan or deployment configuration.
• Exceeding a limit does not affect previously completed requests.
• Error responses never expose internal routing details, model configuration, service credentials, or implementation-specific information.