Limits and errors

Rate limitsCopy Anchor Link

These limits are checked before every request, in this order. A refused request is not charged and takes no hold.

Good to know:

• Fixed windows. Per-minute limits count requests in each calendar minute, so the count resets at the start of every minute.
• Every attempt counts. A request counts toward the per-minute limits even when it is then refused.
• The message has the number. The 429 message always states the limit that applies to you, so read it from there rather than assuming the defaults.
• Streams hold a slot. A streaming request holds its concurrency slot until the stream ends, so close streams you no longer need.

Need higher limits? Contact Helipod support.

Sizes and timeoutsCopy Anchor Link

Error bodyCopy Anchor Link

Errors use the error shape of the format you called, so the official SDKs raise their normal error types.

On /v1/chat/completions and /v1/models (OpenAI style):

{
  "error": {
    "message": "Insufficient balance. Top up your AI balance to continue.",
    "type": "billing_error",
    "code": "insufficient_balance"
  }
}

On /v1/messages and /v1/messages/count_tokens (Anthropic style):

{
  "type": "error",
  "error": {
    "type": "billing_error",
    "message": "Insufficient balance. Top up your AI balance to continue."
  }
}

The Anthropic shape has no code. Branch on the HTTP status and error.type, and on error.code in the OpenAI shape. The type follows the status:

Every response from /v1/chat/completions and /v1/messages, errors included (except 401), carries an x-request-id header. Include it when you contact support.

Errors in a streamCopy Anchor Link

When a streaming request is waiting for a slow model, the gateway has already answered 200 and is sending keep-alive comments. If the model then fails, the status can no longer change, so the error arrives as the last event of the stream:

OpenAI style:

data: {"error":{"message":"The AI provider is unreachable. Please retry.","type":"api_error","code":"upstream_unreachable"}}

data: [DONE]

Anthropic style:

event: error
data: {"type":"error","error":{"type":"api_error","message":"The AI provider is unreachable. Please retry."}}

Failures in the first seconds, before the gateway answers, come back as a normal error response with the real status.

If a stream breaks in the middle of the answer, the connection closes without the usual end (data: [DONE], or message_stop). Treat a stream that ends without it as failed.

Error codesCopy Anchor Link

Errors returned as an HTTP status (any 4xx or 5xx) are never charged. If a stream breaks after the model has started writing, what was generated up to then is charged, like a cancelled stream.

RetriesCopy Anchor Link

• Retry: 429, 500, 502, 503. Use exponential backoff with jitter (for example 1 s, 2 s, 4 s, up to about 30 s) and a limit on attempts. Honour retry-after when it is present. The official OpenAI and Anthropic SDKs already retry these by default.
• Do not retry unchanged: 400, 401, 403, 404, 410, 413. Fix the request, the key or the model first.
• 402: stop and top up. Retrying only repeats the refusal.
• Fall back: for model_unavailable, upstream_unavailable and repeated 5xx on one model, a second model from GET /v1/models keeps your app answering.

A retried request is a new request and is billed on its own if it succeeds. A failed attempt costs nothing.