Errors

Every API error is JSON with a single top-level error object and a meaningful HTTP status code. The status tells you whether a retry can help; the type string is stable and safe to branch on. The shape is identical across every endpoint, including chat completions.

Because INFRO fails over between your connections and route targets automatically, a failure on one of them does not reach you while another can serve. What does surface falls into the small set of statuses below.

Error response body

{
  "error": {
    "message": "Rate limit exceeded: 200 requests per minute for this key.",
    "type": "rate_limit_exceeded",
    "code": null
  }
}

error.messagestringrequired

Human-readable description of the failure. Useful in logs; do not branch on it — the wording can change.

error.typestringrequired

Stable, machine-readable category. One type per status code — see the table below — except on the management API, where a 404 has its own type. Branch on this or on the HTTP status.

error.codestring | nullrequired

A narrower machine-readable code inside the type, when one exists — for example unknown_provider, invalid_attribution, unknown_fallback_model, ambiguous_model, state_too_large or batch_too_large on a 400; key_budget, organization_budget or subscription_required on a 402; model_not_allowed, route_not_allowed, project_archived, key_disabled, organization_suspended, ip_not_allowed, guardrail_blocked or guardrail_unavailable on a 403; version_conflict, key_not_rotatable or environment_in_use on a 409; provider_rate_limited on a 429 your own provider returned; no_provider_connected, connection_out_of_scope or model_not_served on a 503. Often null.

Status codes

For 404, confirm the model ID against GET /v1/models or the models page — IDs use the vendor/model-name form, like anthropic/claude-sonnet-5.

Response cache codes

Three 400 codes (type invalid_request_error) belong to the response cache: cache_ttl_too_long when cache.ttl_seconds, X-INFRO-Cache-TTL or a default TTL is above the plan's maximum; invalid_cache_control when an X-INFRO-Cache* header is malformed; and response_cache_unavailable when turning the cache on in settings while the cache store is not available to your organization. None is retryable unchanged.

Management API errors

The management API (/manage/v1) uses the same envelope and adds two types that appear nowhere else. A 404 there has type not_found and code: "resource_not_found", because it names a project, key or route by ID rather than a model; the same answer is given for a resource that belongs to a project a project-restricted token cannot see. A 409 has type conflict: version_conflict means the resource changed since you read it, so read it again (the ETag header carries the current version) and decide before retrying; project_has_usage means a project cannot be purged and should be archived instead.

Any other 400 or 403 comes from the same validation the console applies to that change, with the same message and code.

MCP gateway errors

The MCP gateway answers a refused tool call with a tool result (isError: true) whose structuredContent.error has the same type, code and message as this envelope, so the model can read it. The new tool-result codes: tool_not_allowed, tool_not_approved and tool_definition_changed (type permission_denied); invalid_tool_arguments (invalid_request_error); tool_result_too_large, tool_result_invalid, upstream_unavailable and upstream_rejected (upstream_error); upstream_timeout (request_timeout). guardrail_blocked and guardrail_unavailable keep their meaning.

Every code, the HTTP refusals the gateway shares with /v1 and its JSON-RPC errors are on MCP gateway errors.

Retry rules

• Retry 408, 429, 502, and 503 with exponential backoff and jitter. These are transient: a later attempt can land on a healthy connection or a fresh rate-limit window. The exceptions are a 503 with code no_provider_connected, connection_out_of_scope or model_not_served, and a 429 with code invalid_api_key_rate_limited, which need a configuration fix first.
• On 429, honor the Retry-After header over your computed delay — it says exactly when capacity frees up. The X-RateLimit-* headers on every response are covered in Rate limits.
• Never retry 400, 401, 402, 404, or 413. They are deterministic — the same request fails the same way. Fix the request, the key, or the model ID; for 402, inspect the code and resolve the subscription or the named budget in the console.

403 sits in between: retrying the identical request will not help, but if provider content moderation was the cause, rewording the content might. Treat it as non-retryable in automated code.

Automatic provider failover

When a connection returns an error or times out before the first token, INFRO moves the request to the next target on the route, or the next of your connections that serves the model. The response names the provider and connection that served it, and route tells you how far down the chain it went — primary when the first served, standby_a when the second did. You only see a 502, 408 or provider 429 when every connection tried failed, and a 503 when none is available at all. Refusals INFRO makes itself (budgets, allowlists, plan limits) are not retried on another connection.

Failover between connections is automatic. For model-level resilience, pass an ordered fallbacks list so the request can complete on a different model when the primary is fully down — see Fallbacks; fallbacks is ignored when model names a route. To choose which connections serve a request and in what order, call a route by name. To choose only which of your providers may serve one request, send routing.providers ({"allow": ["aws-bedrock"]} or {"deny": ["openrouter"]}); it narrows the route's targets, the model's connections and the fallbacks alike, and never widens what your key allows.

Retrying with backoff

import os
import random
import time

import requests

RETRYABLE = {408, 429, 502, 503}

def chat(payload: dict, max_retries: int = 5) -> dict:
    headers = {"Authorization": f"Bearer {os.environ['INFRO_API_KEY']}"}

    for attempt in range(max_retries + 1):
        resp = requests.post(
            "https://api.infro.io/v1/chat/completions",
            headers=headers,
            json=payload,
            timeout=120,
        )
        if resp.ok:
            return resp.json()
        if resp.status_code not in RETRYABLE or attempt == max_retries:
            resp.raise_for_status()

        # Honor Retry-After on 429; otherwise exponential backoff with jitter
        retry_after = resp.headers.get("Retry-After")
        if retry_after:
            delay = float(retry_after)
        else:
            delay = min(2 ** attempt, 30) + random.uniform(0, 1)
        time.sleep(delay)

completion = chat({
    "model": "openai/gpt-5.6-luna",
    "messages": [{"role": "user", "content": "Ping"}],
})
print(completion["choices"][0]["message"]["content"])

Errors mid-stream

Failover and fallbacks only apply before the first token — once a provider begins streaming, it cannot be swapped out. If it drops mid-stream, the SSE stream delivers an event whose payload is the standard error object instead of a chat.completion.chunk:

data: {"error": {"message": "The response stream ended before it completed.", "type": "upstream_error", "code": null}}

The stream then closes without a terminating data: [DONE], and if you requested usage via stream_options, the final usage chunk never arrives. Treat mid-stream errors as retryable: keep or discard the partial output as your application requires, then reissue the request with your normal backoff. The exception is a mid-stream error with code: "guardrail_blocked" or "guardrail_unavailable": an output guardrail stopped the response, and the same request will be stopped the same way. The full event format is covered in Streaming.