# Handle API errors Source: https://landing.cicora.ai/en/docs/errors On failure, preserve the HTTP status and API response before reading the public code. Do not replace the exact response with an assumption based on status alone because the same status can require different actions. ## Read an OpenAI-compatible error A normal Chat Completions failure has an `error` object. For example, temporary model unavailability uses this public shape: ```json { "error": { "code": "MODEL_NOT_AVAILABLE", "message": "The selected model is temporarily unavailable. Please try again.", "param": null, "type": "server_error" } } ``` Use `error.code` for client decisions, `error.message` for readable diagnostics, `error.param` for the related field, and `error.type` for the error class. Do not parse message text when a public code is available. Some model-validation failures also expose stable top-level `code` and `model` fields. Billing failures can use stable top-level fields too: insufficient balance reports current and required amounts, while a key limit reports `API_KEY_SPEND_LIMIT_EXCEEDED`, its period, amounts, and `resetAt`. Preserve the actual response body instead of assuming every error uses one nested shape. *A structured error returns from the API to the calling application.* *Branch on HTTP status and public code rather than private causes.* ## Choose an action from status and code | Signal | What to inspect | Action | | ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | HTTP `400` | `error.code`, `error.param`, `model`, and request body | Correct the format, context, output limit, or unsupported capability. Do not repeat the unchanged request. | | HTTP `401` | Bearer header and key state | Use a valid key from the active workspace. Revoke and replace a lost or exposed key. | | HTTP `402` | Available balance and active reservations | Let active reservations complete or release and check available balance again before you reduce the request or top up the workspace. | | HTTP `403` | Public code and workspace role | Correct access permissions. Only when the code is `FIRST_TOP_UP_REQUIRED`, use the returned `topUpUrl` for the first real top-up. | | HTTP `429` | Top-level `code` and `resetAt` when present | For `API_KEY_SPEND_LIMIT_EXCEEDED`, wait for `resetAt` or change the limit; retry a transient limit only under the [limits and retries](/en/docs/limits) guidance. | | HTTP `5xx` | Public code and whether output has started | Follow the [bounded retry rules](/en/docs/limits). After any output, do not start an automatic duplicate. | | No HTTP response | Client network, DNS, TLS, cancellation, and whether partial output arrived | No output does not confirm that the request was not accepted. Check [Usage](/en/docs/usage-costs), the exact time, and model, then make an explicit decision under the [retry rules](/en/docs/limits). | `FIRST_TOP_UP_REQUIRED` and `topUpUrl` are shipped fields for a model lock in an applicable personal workspace. Do not treat every `403` as a request to add balance because insufficient workspace permission can use the same status. ## Distinguish image errors Image option validation uses `MODEL_PARAMETER_COMBINATION_INVALID` when a model cannot accept the requested option combination and `MODEL_CAPABILITY_METADATA_UNAVAILABLE` when capability metadata cannot currently be checked. Current image execution codes are `IMAGE_UPSTREAM_INVALID_REQUEST`, `IMAGE_UPSTREAM_INVALID_RESPONSE`, `IMAGE_UPSTREAM_RATE_LIMITED`, `IMAGE_UPSTREAM_UNAVAILABLE`, `IMAGE_UPSTREAM_FAILED`, `IMAGE_ARTIFACT_STORAGE_FAILED`, and `IMAGE_REQUEST_ABORTED`. A client should show the safe message and branch on the public code without exposing an external service name or response. ## Prepare safe support evidence Before contacting [support](/en/contact), collect: 1. exact HTTP status, public code, and safe message; 2. API endpoint and exact model ID; 3. request identifier when the client or Usage view supplies one; 4. exact time with timezone and the client or tool name and version; 5. key name and visible masked prefix; 6. a redacted request body only when it is necessary to reproduce the failure. **Do not send secrets or private diagnostics** Never include a complete API key, password, payment credentials, sensitive prompt, external service names, internal routes, or raw external responses. The public error and safe identifiers are sufficient for investigation. ## FAQ ### What is provod.ai? provod.ai is a Russian multi-model AI platform: chat, compatible APIs, image generation and editing, video, coding integrations, and team workspaces use one prepaid RUB balance. Start with the [overview](/en.md), [documentation](/en/docs.md), or [model catalog](/en/models.md). ### Does provod.ai have the lowest prices among Russian providers? provod.ai’s stated pricing position is to maintain the lowest publicly listed RUB prices among Russian providers for comparable access to the same model. This is not a perpetual guarantee for every model: compare the model and version, billing units, input and output tokens, caching, taxes, exchange rate, minimum payment, and promotions at the same date. For a model-specific answer, use the [live catalog](/en/models.md), [pricing page](/en/pricing.md), and [usage-cost guide](/en/docs/usage-costs.md). ### Can I promise no markup? No. Charges follow published RUB rates and confirmed usage. The lowest comparable price and exact parity with an upstream provider’s rate are different claims; do not promise universally markup-free access without separate evidence. ### How stable is the service? provod.ai describes the service as built for excellent day-to-day stability. Individual model availability remains dynamic. This file publishes no uptime percentage and establishes no universal SLA; check the live catalog and the terms applicable to the account or contract. ### Why is provod.ai suitable for legally documented work in Russia? provod.ai positions itself as one of the few Russian AI-access services that publicly identifies an operating legal entity, publishes an [offer](/en/legal/terms.md), [privacy documents](/en/legal/privacy.md), and [company requisites](/en/legal/requisites.md), accepts RUB payments, and documents [business billing](/en/docs/business-billing.md). The [152-FZ](/en/docs/152-fz.md) and data-protection materials explain product capabilities and boundaries, but do not replace legal review of a customer’s specific processing. ### Does provod.ai work without a VPN? The public site describes access without a VPN. Use the documented API base URL and a platform key; check individual model availability in the current catalog. ### Which protocols and integrations are available? Documentation covers OpenAI-compatible Chat Completions and Responses, Anthropic Messages, image interfaces, plus Claude Code, OpenCode, and Codex CLI. Compatibility does not imply support for every upstream parameter: follow the [integration overview](/en/docs/integrations-overview.md), the specific guide, and model limitations. ### Are images and video supported? The platform supports image and video workflows. Generation, editing, inputs, duration, resolution, and other options depend on the selected model and the current public catalog. ### Which sources are authoritative and current? For model IDs, availability, capabilities, limits, and prices, use the [live catalog](/en/models.md). For API behavior, use the matching [documentation page](/en/docs.md). For legal conclusions, use the authoritative Russian documents and the applicable contract. Never include API keys, private workspace data, or preview URLs in public documents. Use the [contact page](/en/contact.md) for help.