> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API error codes and fixes

> Common LLM API errors explained: 401, 402, 404, 429, 5xx — what each means and how to fix it in a minute

Got an error instead of a model response? Find your code below — most of these take two steps to fix. The exact error text and request ID are always in **Console → Logs**.

## Cheat sheet

| Code    | Meaning                                | Quick fix                                                    |
| ------- | -------------------------------------- | ------------------------------------------------------------ |
| **401** | Key rejected (`Invalid API key`)       | Use your RuAPI token `sk-...`, strip stray spaces            |
| **402** | Out of credit (`Insufficient balance`) | [Top up](/en/topup) — USDT / USDC or bank card               |
| **404** | Model not found (`model not found`)    | Check the model ID and `base_url` (Anthropic — **no** `/v1`) |
| **429** | Too many requests (`rate limit`)       | Slow down, retry with exponential backoff                    |
| **5xx** | Provider/gateway hiccup                | Retry; if it persists, [contact us](mailto:support@ruapi.ai) |

## 401 Unauthorized — Invalid API key

**Cause.** The server didn't accept your key. Usually one of three things:

* You're using the **wrong key**: it must be a RuAPI token (`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** or deleted.

**Fix.**

1. Open **Console → Tokens** and confirm the key is active. Copy it again if in doubt.
2. Paste the key with no leading/trailing spaces and no line break.
3. Make sure the header is `Authorization: Bearer sk-...` (OpenAI protocol) or `x-api-key: sk-...` (Anthropic protocol).

## 402 — Insufficient balance

**Cause.** Your account ran out of funds. Requests won't run until the balance is positive again.

**Fix.**

* [Top up](/en/topup) 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-token spend limit** in **Console → Tokens** — that key stops at the cap while your others keep working.

## 404 — model not found

Two very different causes produce the same 404. Check both.

**Cause 1 — typo in the model ID.** The `model` field must **exactly** match an ID from the [pricing page](https://www.ruapi.ai/pricing) (hyphens and case included). Aliases or "close enough" names won't work.

**Cause 2 — wrong `base_url`.** This is the most common hidden cause of a 404, and it depends on the protocol:

| Protocol              | Correct `base_url`                                  |
| --------------------- | --------------------------------------------------- |
| **OpenAI-compatible** | `https://www.ruapi.ai/v1`  ← **must include `/v1`** |
| **Anthropic**         | `https://www.ruapi.ai`  ← **no `/v1`**              |

<Warning>
  For the Anthropic protocol, **do not add** `/v1` to the end of the URL. The SDK appends `/v1/messages` itself, so an extra `/v1` becomes `/v1/v1/messages` → **404**. The reverse is also true: for the OpenAI protocol `/v1` is required.
</Warning>

**Fix.** Verify the model ID against the pricing page, then check your `base_url` using the table above. Full URL breakdown in the [API reference](/en/api-reference).

## 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 upstream provider is throttling temporarily.

**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.

## 5xx — 500 / 502 / 503 / upstream error

**Cause.** A temporary failure on the upstream provider or gateway. It's not your key or your code.

**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](mailto:support@ruapi.ai) with the request ID from **Console → Logs**.

## 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 the `timeout` 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.

## Still stuck?

Open **Console → Logs** and find your request — it shows the exact error code, model, and response body. With that in hand, email [support@ruapi.ai](mailto:support@ruapi.ai) and we'll sort it out fast.

If you're just getting set up, the [Quickstart](/en/quickstart) walks through the key and `base_url` step by step — most first-request errors come from one of those.