Решение ошибок Claude API: 400, 401, 403, 404, 413, 429, 500, 529 — полный гайд

Запрос «api error claude» стабильно держится в Яндексе с частотой около 1 000 показов в месяц — это второй по частотности технический запрос в нише Claude после «claude code». И, в отличие от большинства «как купить»-запросов, это чистая боль: разработчик уже работает с API, у него упало, он ищет решение. Прямо сейчас, в моменте.

В этой статье — полный каталог ошибок Anthropic API: каждый код (400, 401, 403, 404, 413, 429, 500, 529, 529), причина, как диагностировать и как починить. С конкретными curl-примерами, примерами ответов LiteAI/Bifrost, и единой таблицей для шпаргалки.

Если после прочтения у вас всё ещё падает — в конце статьи рабочий runbook для 90% случаев в три шага.

Что такое ошибка Claude API и где она возникает

Когда ваш код отправляет запрос в Anthropic API (POST https://api.anthropic.com/v1/messages), сервер может ответить двумя способами:

1. HTTP-уровень. Код 4xx/5xx + JSON-тело с полем error.type и error.message. Это структурированная ошибка, описанная в спеке Anthropic.
2. Сетевой уровень. Таймаут, ECONNRESET, DNS error, TLS reset. Это ошибки стека (Node.js fetch, curl, Python requests), у них нет HTTP-кода.

LiteAI-прокси (https://api.liteai.tech/anthropic) и официальный Anthropic API возвращают одинаковые структурированные ошибки — потому что LiteAI просто проксирует запросы в Bifrost/Anthropic с вашим sk-bf-… ключом. Так что один и тот же гайд закрывает обе интеграции.

Полная карта ошибок

Код	Что значит	Когда возникает	Решается на клиенте?	Критичность
400	Bad Request	Тело запроса некорректное	Да, фикс кода	🟡
401	Unauthorized	Нет/неверный API-ключ	Да, проверить ключ	🔴
403	Permission Denied	Ключ не имеет прав на модель/эндпоинт	Да	🟡
404	Not Found	Эндпоинт не существует или регион не тот	Да	🟡
413	Payload Too Large	Запрос больше лимита (image/pdf)	Частично	🟡
429	Too Many Requests	Rate limit / quota exceeded	Частично (retry)	🟡
500	Internal Server Error	Серверная ошибка Anthropic/Bifrost	Retry	🟠
529	Overloaded	Все модели заняты, попробуйте позже	Retry (с backoff)	🟠
503/504	Unavailable/Gateway	Сетевая ошибка или региональная деградация	Retry	🟡
521/522/523/524	Cloudflare	Cloudflare не может достучаться до upstream	Retry	🟡

Все ошибки кроме 401/403, как правило, временные и решаются повтором с увеличивающимся интервалом. 401 и 403 — это код-баг или проблема учётки, retry не поможет.

400 — Bad Request

Текст ответа:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages: roles must alternate between \"user\" and \"assistant\""
  }
}

Типичные причины (RU-разработчики, по опыту LiteAI):

1. roles must alternate — в messages массиве идут подряд два сообщения с одной ролью. Например [{role:"user"}, {role:"user"}]. Решение: разбавить ассистентом или объединить содержимое.
2. messages must be non-empty — пустой массив. Минимум одно user-сообщение.
3. temperature: invalid value — больше 1.0 или меньше 0. Claude API принимает 0.0–1.0.
4. max_tokens: too large — больше 8192 для Opus 4.8 / Sonnet 4.6. Это лимит per-request, а не per-month.
5. system: too long — больше 100K токенов в system-промпте. Сократить или вынести в Prompt Caching.
6. unknown model — указан claude-4-opus вместо claude-opus-4-8. Список моделей: Anthropic docs → Models.

Диагностика:

curl https://api.liteai.tech/anthropic/v1/messages \
  -H "x-api-key: $LITEAI_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{...}' -i | head -20

Если ошибка — смотрите поле error.type (обычно invalid_request_error) и error.message. Они почти всегда указывают на конкретное поле в вашем JSON.

Как предотвратить: используйте Anthropic SDK вместо raw JSON. SDK проверяют типы на этапе компиляции.

401 — Unauthorized

Текст ответа:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }
}

Причины:

1. Не передан x-api-key header. Проверьте, что устанавливаете его в каждом запросе, а не только в первом.
2. Ключ истёк или отозван. На LiteAI ключ sk-bf-… живёт, пока не израсходован баланс. Если баланс = 0, ключ формально валиден, но запросы возвращают 402 Payment Required (см. ниже — это специфика LiteAI), а не 401.
3. Ключ перепутан с prod/dev. Если у вас две среды и две пары ключей, легко перепутать.
4. ANTHROPIC_AUTH_TOKEN vs x-api-key. В Anthropic SDK есть два способа авторизации: x-api-key header и Authorization: Bearer. Если используете SDK — проверьте, что задали именно api_key, а не auth_token.

Быстрый тест ключа:

curl https://api.liteai.tech/anthropic/v1/models \
  -H "x-api-key: $LITEAI_KEY" \
  -H "anthropic-version: 2023-06-01" | jq

Если ответ — массив моделей, ключ валиден. Если authentication_error — ищем причину.

403 — Permission Denied

Текст ответа:

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Your API key does not have access to claude-opus-4-8"
  }
}

Причины:

1. Модель недоступна для вашего ключа. Например, Opus 4.8 включён не на всех тарифах. У LiteAI Opus 4.8 / Sonnet 4.6 / Haiku 4.5 / fable-5 доступны всем.
2. Региональный блок. Если используете region: "EU" и модель не имеет EU-инстанса (бывает редко с Anthropic).
3. Org-level permission. В Anthropic Console через claude.ai можно создавать кастомные permissions для org.

Диагностика:

import anthropic
client = anthropic.Anthropic(api_key="sk-bf-...")
try:
    client.messages.create(model="claude-opus-4-8", max_tokens=10, messages=[{"role":"user","content":"ping"}])
except anthropic.PermissionDeniedError as e:
    print(e)

В SDK ошибка превращается в типизированное исключение с понятным message.

404 — Not Found

Текст ответа (Anthropic-специфика):

{"type":"error","error":{"type":"not_found_error","message":"/v1/messagez: model not found"}}

или для LiteAI: пустой 404 с HTML-телом nginx.

Причины:

1. Опечатка в пути. /v1/messages против /v1/messagez. SDK этого не простят, raw curl — да.
2. Неправильный ANTHROPIC_BASE_URL. Если LiteAI — это https://api.liteai.tech/anthropic. Если Anthropic direct — https://api.anthropic.com.
3. Региональная маршрутизация. AWS/GCP-регионы имеют разные hostnames; 404 часто значит «вы в неправильном регионе».
4. Модель не существует в данном эндпоинте. Например, claude-2 уже устарел.

Диагностика: проверьте ANTHROPIC_BASE_URL через echo, проверьте что URL без trailing slash, проверьте что модель существует через эндпоинт /v1/models.

413 — Payload Too Large

Текст ответа:

{"type":"error","error":{"type":"request_too_large","message":"Request exceeds the maximum size (max: 32 MB for non-vision)"}}

Причины:

1. Картинка / PDF больше лимита. Лимит на одну картинку — 5 MB, на PDF — 32 MB. Если больше — 413.
2. Длинный контекст. Один запрос с 200K токенов контекста плюс base64-картинка может уйти за 32 MB. Решение — отправить картинку через Files API или сжать.
3. Много tool definitions. Каждый tool — это ~500 токенов. 100 tools × 500 = 50K токенов JSON. Антропик принимает до ~50 tools per request, но payload вырастает.

Решения:

• Сжимать изображения перед отправкой (sharp для Node, Pillow для Python).
• Использовать Files API для больших PDF — Anthropic API поддерживает file_id ссылку вместо inline base64.
• Разбивать на чанки длинный контекст через prompt caching и summarize.

429 — Too Many Requests

Текст ответа:

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Number of request tokens per minute (RPM) exceeded: 50"
  }
}

Это самая частая ошибка в проде. Anthropic имеет multi-tier rate limit:

Tier	RPM	TPM	Когда доступен
Free	5	25K	первый день
Build Tier 1	50	100K	после $5 трат
Build Tier 2	1000	1M	после $50 трат
Build Tier 3+	4000+	4M+	после $500+ трат

На LiteAI rate limits мягче (мы не даём per-minute жёсткий cutoff — отдаём что есть, при пике задерживаем), поэтому 429 на LiteAI обычно значит «прокси-узел перегружен», а не «вы превысили лимит».

Решения:

1. Exponential backoff — 1s, 2s, 4s, 8s, 16s, 32s с джиттером.
2. Batch requests — если API поддерживает batches (Anthropic пока нет, OpenAI и Google есть), submit offline batch.
3. Prompt Caching — снижает TPM в 10x (с 100K до 10K на повторный system-prompt).
4. Параллелизация через workers — несколько процессов с разными ключами.
5. Streaming — снижает TTFB и время на слот.

Пример retry-логики на Python (стабильно работает на проде):

import time, random
import anthropic

def with_retry(fn, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return fn()
        except anthropic.RateLimitError:
            if attempt == max_attempts - 1: raise
            delay = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)

500 — Internal Server Error

Текст ответа:

{"type":"error","error":{"type":"api_error","message":"Internal server error"}}

Что значит: серверная ошибка у Anthropic или LiteAI. Ваш код не виноват.

Решение:

1. Retry с exponential backoff — Anthropic обычно чинит за 1–30 секунд.
2. Открыть status page: status.anthropic.com или наш канал.
3. Если 5xx продолжается > 5 минут — это прод-инцидент. Можно временно переключиться на OpenAI API или DeepSeek через OpenRouter.

На проде LiteAI-Bifrost 500-е за последние 90 дней были 3 раза, все длились < 90 секунд.

529 — Overloaded

Текст ответа:

{"type":"error","error":{"type":"overloaded_error","message":"Anthropic API is temporarily overloaded, please retry"}}

Отличие от 500: 529 — это «все чипы заняты». Это нормальное состояние в пиковые часы (11:00–14:00 ET, 14:00–17:00 UTC). В моменте модели реально перегружены.

Решение: то же что и 500 — retry с backoff. Но разница в стратегии:

• Если 5xx — retry быстрее (1, 2, 4, 8 сек).
• Если 529 — retry медленнее (10, 20, 40 сек). Чипы могут освободиться только через минуту.

Также помогает fallback на другую модель:

models_in_order = ["claude-opus-4-8", "claude-sonnet-4-6", "claude-haiku-4-5"]
for model in models_in_order:
    try:
        return client.messages.create(model=model, ...)
    except anthropic.APIStatusError as e:
        if e.status_code in (500, 529) and model != models_in_order[-1]:
            continue  # fallback
        raise

Haiku 4.5 в ~10 раз дешевле Opus 4.8 и никогда не перегружается (его инференс на отдельном пуле). Когда Opus перегружен — фолбэк на Haiku не сэкономит на логике, но сэкономит на ошибках.

503/504 — Unavailable / Gateway Timeout

503: сервер временно не доступен, обычно прокси-слой (Cloudflare, AWS ALB). 504: время ожидания upstream-сервера вышло (nginx proxy_read_timeout).

На LiteAI 504 — это наш nginx не дождался Bifrost. У нас в логах это редкое событие, обычно коррелирует с большими пакетами или сетевыми всплесками. Retry-логика работает так же, как с 500.

Runbook: что делать, когда упало (3 шага за 90 секунд)

Если вы читаете это в режиме «у меня прямо сейчас всё сломалось» — вот быстрый алгоритм:

Шаг 1. Определите код (5 секунд).

curl https://api.liteai.tech/anthropic/v1/messages \
  -H "x-api-key: $LITEAI_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":10,"messages":[{"role":"user","content":"ping"}]}' \
  -s -w "\n%{http_code}\n"

Если ответ 200 OK — ваш основной код ломает что-то конкретное (модель, payload), проблема в нём. Если 401/403 — ключ. Если 500/529 — retry.

Шаг 2. Проверьте ключ (10 секунд).

curl https://api.liteai.tech/anthropic/v1/models \
  -H "x-api-key: $LITEAI_KEY" \
  -H "anthropic-version: 2023-06-01" | jq 'if type == "array" then "✅ OK" else .error.message end'

Если ✅ OK — ключ валиден. Если ошибка — смотрите текст ошибки.

Шаг 3. Проверьте статус провайдера (30 секунд).

• status.anthropic.com — официальный статус Anthropic
• Telegram-канал LiteAI (при проблемах мы пишем туда) — там видно, если падает наш Bifrost

Если у LiteAI всё хорошо, а Anthropic degraded — подождите 5–10 минут. Если у всех всё хорошо — баг в вашем коде, смотрите поле error.message внимательнее.

Лучшие практики для продакшена

1. Всегда используйте SDK. Anthropic SDK ловит 95% ошибок в типизированных исключениях — RateLimitError, AuthenticationError, NotFoundError. Это быстрее, чем парсить JSON.

2. Exponential backoff с jitter. На каждом retry увеличивайте паузу × 2 и добавляйте случайный jitter ±20%. Это уменьшает «thundering herd», когда 100 воркеров ретраят одновременно.

3. Мониторьте retry_after_header. Некоторые 429 содержат Retry-After: 30 — соблюдайте его вместо своей backoff-стратегии.

4. Логируйте request-id. Каждый ответ от Anthropic имеет header request-id: req_…. Если ошибка воспроизводится — этот ID критически важен при обращении в поддержку.

5. Разделяйте retry-логику по типам ошибок:

• 401, 403 — НЕ retry, алерт.
• 400 — НЕ retry, fix код.
• 404 — НЕ retry, проверьте URL.
• 413 — НЕ retry, уменьшите payload.
• 429 — retry с backoff.
• 500, 502, 503, 504, 529 — retry с backoff.
• Таймауты — retry.

6. Только в LiteAI: оплата. Если у вас LiteAI-ключ и он возвращает 402 Payment Required, это значит баланс = 0. Пополните на /pricing — баланс не сгорает, минимальный пакет 30 ₽ / 1M токенов.

Когда обращаться в поддержку

Если вы прошли все три шага runbook'а, проблема не воспроизводится на Haiku 4.5, статус Anthropic и LiteAI чистый — соберите:

1. request-id из ответа.
2. Timestamp в UTC (с точностью до секунды).
3. Полный curl с redacted-ключом (замените sk-bf-... на sk-bf-REDACTED).
4. Ваш сценарий: что вы пытались сделать и что должно было произойти.

И напишите в Telegram @liteaitech_bot или на support@liteai.tech. С поддержкой LiteAI время реакции — обычно в течение часа в рабочее время.

Что дальше

Если вы систематически ловите одну и ту же ошибку:

• Постоянные 429 → ваш кейс больше, чем tier. Переходите на Tier 2+, используйте prompt caching, или режьте параллелизм.
• Постоянные 529 → вы работаете в пиковое время (16:00 UTC). Планируйте batch-задачи на ночь (00:00–08:00 UTC), когда трафик в 4 раза меньше.
• <string>: OpenAI API error 400 из Claude Code → часто значит, что Anthropic SDK в Claude Code использует OpenAI-формат через LiteAI-маршрут. Убедитесь, что ANTHROPIC_BASE_URL ведёт на /anthropic/v1, а не на /v1 (OpenAI-формат). См. статью про setup Claude Code.

Для анлока прод-возможностей — загляните в pillar про Claude Code и в подписку Claude Code в РФ — там объясняется, как избежать 90% боли с лимитами и оплатой, которая и приводит к этим ошибкам.