Cheat sheet
401 Unauthorized — Invalid token
Cause. The server didn’t accept your key. Possible reasons:- You’re using the wrong key: it must be a RuAPI key (
sk-...), not an official OpenAI key (sk-...) or Anthropic key (sk-ant-...). OpenAI and RuAPI keys look alike, but only the one from your RuAPI Console works here. - A stray space or newline snuck into the key during copy-paste — a very common one.
- The key is disabled, deleted or expired.
- The key hit its own credit limit (if you set one when creating it). Your overall balance can still be positive — it’s this particular key that’s capped.
Fix.
- Open Console → API Keys and confirm the key is active, not expired and not over its limit. Copy it again if in doubt.
- Paste the key with no leading/trailing spaces and no line break.
- Make sure the header is
Authorization: Bearer sk-...(OpenAI protocol) orx-api-key: sk-...(Anthropic protocol).
403 — not enough balance
Cause. Your account ran out of funds (or doesn’t have enough for this request). Requests won’t run until you top up. Fix.- Top up in USDT / USDC or by bank card — minimum $5. Crypto is usually credited within 1–5 minutes, card payments within seconds.
- Note: agentic tools (Claude Code, Cline, autonomous agents) and long context burn tokens fast — dozens of requests a minute is normal.
- To avoid draining your whole balance on one project, set a per-key credit limit in Console → API Keys — that key stops at the cap while your others keep working.
403 — the key isn’t allowed to use the model, or its limit is too low
These errors are about the key’s own settings, not your account balance.404 — wrong URL
Cause. The request went to a path that doesn’t exist. It’s almost always thebase_url, and the right value depends on the protocol:
Fix. Check your
base_url using the table above. Full URL breakdown in the API reference.
400 — a problem with the request itself
Cause. The model can’t accept what’s in the request;error.message gives the exact reason. The most common ones:
- A tool schema (JSON Schema) the model doesn’t understand. The message quotes the model provider, e.g.
Invalid JSON payload receivedorUnknown name …. For Gemini models we strip what Gemini doesn’t accept ($schema,additionalProperties, etc.) before sending; anything left is shown to you as is. - An image or file can’t be opened: the URL isn’t publicly reachable, the file is broken, or the base64 data is truncated (e.g.
Invalid image url). - Parameters for continuing a previous response on
/v1/responses: see below.
error.message says. Such errors used to show up as 500 sometimes; now they come back as 400 with the reason.
Video generation: reference_video_task_id error codes. When you reuse a generated video with reference_video_task_id, you may get ref_task_not_found, ref_task_not_ready, ref_task_failed, ref_task_expired, ref_task_unavailable or unsupported_by_channel, and nothing is charged. What each code means and what to do is in the “Reusing a generated video” section of the video generation guide.
Video generation: Seedance moderation errors. Codes such as input_contains_real_person, input_copyright_restricted, InputImageSensitiveContentDetected.PrivacyInformation, ...PolicyViolation or OutputVideoSensitiveContentDetected (the first two in the submission response, the official ModelArk codes in the task’s error field) mean that the request or the finished video failed the Seedance model’s own moderation. You’re not charged for a rejected task. For an explanation of each code, see a real person in a photo or video and copyright and prohibited content.
/v1/responses: continuing a previous response isn’t supported
RuAPI doesn’t store conversations on the server, so the Responses API doesn’t support previous_response_id, conversation, or background mode. A request with any of them gets an immediate 400 (nothing is charged), and the message names the parameter. Send the full conversation history in input every time — Codex CLI does this by default, so it isn’t affected.
503 — model not available (model_not_found)
Cause. Almost always, there is no model with that ID in the catalog. Themodel field must exactly match an ID from the pricing page — hyphens, prefix and letter case included (GLM-5.2 and glm-5.3 are spelled differently; kimi/kimi-k3 needs its prefix). Aliases or “close enough” names won’t work.
The response has "code": "model_not_found", and error.message reads “Model gpt-5 is not available. Check the exact model name on the Pricing page or try again later.”
Fix. Copy the model ID from the pricing page and paste it into model unchanged. If the ID is definitely right, the model is temporarily unavailable — retry in a minute.
429 — Too Many Requests / rate limit
Cause. Too many requests in a short window — either your code is firing them in a burst, or the model provider is temporarily throttling requests. RuAPI also limits how often each account can send requests; normal work, agents included, stays well under that limit. Fix.- Slow down and retry with exponential backoff: 1s, 2s, 4s, 8s…
- Spread the load over time; don’t send hundreds of requests at once.
- For batch jobs, add a small pause between requests or cap the number of parallel workers.
video_concurrency_limit. An account can have at most 3 unfinished video tasks at a time. Any further task is rejected immediately with 429, the code video_concurrency_limit and the header Retry-After: 30; it is not charged. Wait until one of your tasks finishes, then submit again. If you need more parallel tasks, contact support at support@ruapi.ai or on Telegram @RuAPI_Support. Details are in the video generation guide.
5xx — 500 / 502 / 503 / upstream error
Cause. A temporary failure at the model provider or in the gateway. It’s not your key or your code. (The exception is a503 with the code model_not_found — that’s almost always a typo in the model name, see above.)
Fix.
- Retry after a few seconds — it usually goes through on the second or third attempt.
- Wrap your calls in retry-with-backoff so these blips don’t crash your script.
- If the error sticks around and shows up across different models, email support@ruapi.ai with the
request idfrom the error text.
Streaming cutoffs and timeouts
Long answers (large context, reasoning models, code generation) can take tens of seconds. If the connection drops mid-stream or the client times out — raise thetimeout in your SDK (60–120s or more for heavy requests), make sure no proxy between you and RuAPI is killing long SSE connections, and don’t disable streaming for long responses — streaming is exactly what keeps the request from timing out.
Claude Code errors
“Unable to connect to Anthropic services”, “Invalid API key · Please run /login” and other errors shown by Claude Code itself are covered on the Claude Code in Russia page.The error comes from OpenAI, Google, Anthropic or DeepSeek directly, not from RuAPI
If you call the official API directly and get refused because of your region, here is each error explained:unsupported_country_region_territory(403, OpenAI) — OpenAI: unsupported_country_region_territoryUser location is not supported for the API use(400, Gemini) — Gemini: User location is not supportedRequest not allowed(403) andnot allowed from unsupported countries(400, Claude) — Claude: Request not allowed
Insufficient Balance (402) — DeepSeek: 402 Insufficient Balance.
Still stuck?
Message support on Telegram or email support@ruapi.ai with the error code, the fullerror.message text (including the request id), the model name and the time of the request — and we’ll sort it out fast.
If you’re just getting set up, the Quickstart walks through the key and base_url step by step — most first-request errors come from one of those.