Errors and rate limits

Error formatCopy Anchor Link

Errors use the format of the endpoint you called, so your SDK raises its usual exception types.

OpenAI endpoints (/v1/chat/completions, /v1/responses, and /v1/models without an anthropic-version header):

{
  "error": {
    "message": "Your organization has no remaining credit. Top up to continue.",
    "type": "insufficient_quota",
    "code": "insufficient_credits",
    "param": null
  }
}

Anthropic endpoints (/v1/messages, /v1/messages/count_tokens, and /v1/models with an anthropic-version header):

{
  "type": "error",
  "error": {
    "type": "billing_error",
    "message": "Your organization has no remaining credit. Top up to continue."
  }
}

Every error response also carries the header x-interodin-error-code with the code from the table below. Branch on the HTTP status and on error.code (OpenAI format) or on the x-interodin-error-code header (any format). In the Anthropic format several codes share one error.type (for example, all three 403 codes are permission_error), so the header is the reliable way to tell them apart. Don't match on message, because the wording can change.

Error codesCopy Anchor Link

Every response, errors included, carries an x-request-id header. Include the id when you contact support. Because we never store request content, the id is how we find your request.

If your client disconnects before the reply is complete, the request appears in your request logs with status 499 (client_closed_request). You never receive this status yourself, because the connection is already closed. If you abort a request that is not streaming, you are billed for the input in full plus an estimate of the output produced so far.

Errors during a streamCopy Anchor Link

Once a stream has started, the status code is already 200. If generation fails after that point, the stream ends with an error event in the same format as the endpoint:

• Chat Completions: a final data: {"error": {...}} line.
• Responses: an event: error with a {"type": "error", "code": "...", "message": "...", "param": null} payload.
• Messages: an event: error with a {"type": "error", ...} payload.

A failure during a stream is reported as upstream_unavailable. Input tokens are billed in full. Output is billed for what was delivered before the failure, estimated from the delivered text when the model never reported usage.

Rate limitsCopy Anchor Link

Limits apply per API key and per organization, per minute, to both requests and tokens (input plus output). Responses from the generation endpoints (/v1/chat/completions, /v1/responses, /v1/messages, /v1/messages/count_tokens) report the current window. They report whichever of your key's or your organization's windows is closer to its limit. GET /v1/models doesn't send these headers, and neither do errors that happen before the rate-limit check, such as 401 or a 400 for an invalid request.

When you exceed a limit you get 429 rate_limit_exceeded with a Retry-After header, in seconds. Your organization can also have only a limited number of requests in flight at once; past that you get 429 concurrency_limit with Retry-After: 1. Token counting with /v1/messages/count_tokens is free and works at a zero balance, but it still counts toward the rate limits and the in-flight cap. If you need higher limits, contact support.

RetryingCopy Anchor Link

Retry only these responses:

• 429
• 500
• 502
• 504
• network errors

Use exponential backoff with jitter, and honor Retry-After when it is present. Never retry other 4xx errors unchanged, because they will fail again.

The OpenAI and Anthropic SDKs already retry these statuses. You can raise the retry count and the timeout:

import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://api.interodin.com/v1',
  apiKey: process.env.INTERODIN_API_KEY,
  maxRetries: 4,
  timeout: 120_000,
})

const models = await client.models.list()
console.log(models.data.map((m) => m.id))