Коды ошибок Claude API

Любая ошибка возвращается в JSON с одинаковым конвертом, поэтому ветвиться можно по error.type, не разбирая текст сообщения:

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

Сопоставляйте HTTP-статус и error.type, но никогда не текст сообщения: сообщение — это проза, его могут переформулировать, а тип — это контракт. В официальных SDK это означает ловить типизированные классы исключений, а не искать подстроки. Эта страница построена наоборот только потому, что в момент поломки перед глазами у вас именно сообщение.

Все коды

401 — invalid x-api-key

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

Почему возникает

• Заголовок x-api-key отсутствует или пуст — чаще всего переменная окружения не задана в том процессе, который реально делает запрос.
• Ключ уходит не в том заголовке. ANTHROPIC_API_KEY отправляется как x-api-key, а ANTHROPIC_AUTH_TOKEN — как Authorization: Bearer. Верный ключ в неверном заголовке даёт ту же ошибку.
• Заданы обе переменные сразу, поэтому уходят оба заголовка и запрос отклоняется. Пустая строка тоже считается заданным значением.
• Ключ отозван или истёк, если он выпускался с датой окончания.
• С ключом всё в порядке, но base URL ведёт туда, где про этот ключ никогда не слышали.

Что делать

• Выведите первые несколько символов переменной внутри того же процесса, который падает. Большинство 401 — это проблема окружения или кавычек, а не ключа.
• Оставьте одну переменную, вторую снимите. Это самая частая причина, когда используется свой base URL.
• Проверьте, что ключ активен в панели, а base URL соответствует его издателю.

Проверьте, что уходит на самом деле

# Is the variable set in THIS shell?
echo "${ANTHROPIC_API_KEY:0:12}…"
# Is a competing variable also set?
env | grep -E 'ANTHROPIC_(API_KEY|AUTH_TOKEN|BASE_URL)'

curl https://api.apitoken.sale/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

Другие формы той же ошибки

• 401 - {'type': 'error', 'error': {'type': 'authentication_error', 'message': 'invalid x-api-key'}}
• litellm.AuthenticationError: AnthropicException - invalid x-api-key
• anthropic.AuthenticationError
• claude code 401 custom ANTHROPIC_BASE_URL
• cursor bad user api key unauthorized anthropic

Короткая ссылка: https://apitoken.sale/e/invalid-api-key · Идентично на api.anthropic.com и на этом шлюзе.

429 — превышен лимит запросов

HTTP 429
{"type":"error","error":{"type":"rate_limit_error","message":"This request would exceed your organization's rate limit of 80,000 input tokens per minute. Please reduce the prompt length or the maximum tokens requested, or try again later."}}

Почему возникает

• Превышен поминутный потолок по токенам или запросам. Число в сообщении — ваш собственный лимит, поэтому у разных аккаунтов оно разное.
• Всплеск без ограничения параллелизма — обычно это параллельный проход по большому списку.
• Ретраи, наложенные поверх запросов, которые и вызвали первый 429: всплеск от этого растёт, а не рассасывается.
• Один очень большой промпт может исчерпать поминутный бюджет сам по себе — поэтому в сообщении предлагается ещё и сократить промпт, а не только подождать.

Что делать

• Читайте заголовок Retry-After вместо того, чтобы угадывать паузу.
• Официальные SDK уже ретраят 429 и 5xx с экспоненциальной задержкой (по умолчанию дважды) — поднимите max_retries вместо своего цикла.
• Ограничьте параллелизм на стороне клиента. Семафор вокруг вызова лечит больше 429, чем любая политика ретраев.
• Не путайте это с квотой подписки — см. запись про лимит использования ниже. Это разные системы и разные решения.

Пусть SDK сам отступает

import anthropic

client = anthropic.Anthropic(max_retries=5)  # retries 429 and 5xx with backoff

Другие формы той же ошибки

• Number of request tokens has exceeded your per-minute rate limit
• anthropic.RateLimitError
• claude api 429 too many requests

Короткая ссылка: https://apitoken.sale/e/rate-limit · Идентично на api.anthropic.com и на этом шлюзе.

529 — Overloaded

HTTP 529
{"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}

Почему возникает

• Мощности апстрима временно перегружены. 529 говорит о состоянии сервиса, а не о вашем запросе.
• Ошибка кучкуется во время инцидентов: тот же самый запрос обычно проходит через несколько минут без единого изменения.

Что делать

• Ретрайте с экспоненциальной задержкой и джиттером. Никогда в плотном цикле — именно это и создаёт затор.
• Обратите внимание: статус 529, а не 503. Некоторые HTTP-клиенты и прокси считают ретраибельными только фиксированный набор кодов, и 529 в него часто не входит — тогда ретрай, на который вы рассчитываете, просто не срабатывает.
• Для чувствительных к задержке сценариев предусмотрите переход на модель поменьше — она обычно менее загружена.

Другие формы той же ошибки

• API Error: 529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}
• anthropic api overloaded error repeated 529
• claude 529 vs 429

Короткая ссылка: https://apitoken.sale/e/overloaded · Идентично на api.anthropic.com и на этом шлюзе.

400 — закончились кредиты Anthropic

HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"Your credit balance is too low to access the Anthropic API. Please go to Plans & Billing to upgrade or purchase credits."}}

Почему возникает

• У организации Anthropic, которой принадлежит ключ, закончились кредиты API. Кредиты API — отдельный кошелёк, не связанный с подпиской Pro или Max.
• Подписчик Pro или Max видит это потому, что инструмент авторизуется API-ключом, а не подпиской: подписка не оплачивает вызовы API.
• Отключено автопополнение или не прошла оплата привязанной картой.

Что делать

• Проверьте, чем именно авторизуется падающий инструмент — ключом или входом по подписке. Эта ошибка всегда про кредиты API.
• Пополните кредиты организации или включите автопополнение, чтобы длинные задачи не обрывались на середине.
• На этом шлюзе аналогичная ситуация возвращает 402 с другим текстом — см. запись про недостаточный баланс.

Другие формы той же ошибки

• claude credit balance is too low but I have credits
• claude pro credit balance too low
• your credit balance is too low to access the anthropic api

Короткая ссылка: https://apitoken.sale/e/credit-balance-too-low · Идентично на api.anthropic.com и на этом шлюзе.

Лимит использования Claude исчерпан — это квота подписки, а не ошибка API

Claude usage limit reached. Your limit will reset at 3pm (America/New_York)

Почему возникает

• Это потолок подписки Claude Pro или Max, а не HTTP-ошибка API. Сообщение приходит из приложений и из Claude Code, когда вход выполнен по подписке.
• Квоты считаются в скользящем окне (обычно пятичасовое окно сессии плюс недельный потолок), поэтому при интенсивной работе недельный лимит может закончиться задолго до конца недели.
• К 429 это отношения не имеет: у API лимиты — это пропускная способность в минуту, а здесь — квота тарифного плана.

Что делать

• Дождитесь указанного времени сброса — оно названо прямо в сообщении, и это скользящее окно, а не календарная граница.
• Уменьшите объём каждого запроса. Длинные диалоги пересылают всю историю на каждом шаге, поэтому подрезка контекста заметно растягивает квоту.
• Если работа не может ждать сброса, доступ к API тарифицируется потокенно, а не квотой плана, поэтому недельного потолка там нет. Это честная разница: другой способ учёта, а не способ обойти ограничение.

Другие формы той же ошибки

• Claude AI usage limit reached
• claude weekly limit reached
• claude max 20x weekly limit
• when does claude usage limit reset
• лимит claude исчерпан когда сбросится

Короткая ссылка: https://apitoken.sale/e/usage-limit-reached · Приходит из приложений и подписок Anthropic, а не от этого шлюза.

400 — промпт слишком длинный

HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 212164 tokens > 199999 maximum"}}

Почему возникает

• Запрос превышает контекстное окно модели. Два числа в сообщении — размер вашего промпта и потолок для этой модели.
• Агентный цикл, который дописывает в историю каждый результат инструмента и никогда её не подрезает.
• Большие файлы или документы вставлены текстом вместо ссылки.

Что делать

• Считайте заранее: эндпоинт count_tokens даёт точное число для конкретной модели. Не оценивайте токенизатором другого вендора — он заметно занижает счёт для Claude.
• Вычищайте старые результаты инструментов из истории или включите серверную компакцию, чтобы ранние ходы сворачивались в сводку, а не пересылались дословно.
• Большие документы загружайте один раз через Files API и ссылайтесь на file_id.

Другие формы той же ошибки

• claude prompt is too long tokens > maximum
• claude 200k context limit error

Короткая ссылка: https://apitoken.sale/e/prompt-too-long · Идентично на api.anthropic.com и на этом шлюзе.

400 — tool_use без парного tool_result

HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"`tool_use` ids were found without `tool_result` blocks immediately after: toolu_… Each `tool_use` block must have a corresponding `tool_result` block in the next message."}}

Почему возникает

• Ход ассистента запросил один или несколько инструментов, а следующее сообщение вернуло результат не для каждого из них.
• В историю добавили только текст вместо всего содержимого ответа, из-за чего блоки tool_use молча потерялись.
• Инструменты запрашивались параллельно, а результаты разложили по нескольким сообщениям вместо одного.
• Инструмент упал, и код не отправил результат вместо того, чтобы отправить результат с ошибкой.

Что делать

• Добавляйте в историю всё содержимое ответа целиком, а не только текст.
• Возвращайте все tool_result одного хода внутри одного пользовательского сообщения. Разбивка вдобавок отучает модель делать параллельные вызовы.
• При падении инструмента всё равно верните tool_result с признаком ошибки — не пропускайте его.

Другие формы той же ошибки

• tool_use ids were found without tool_result blocks
• claude code tool_result error

Короткая ссылка: https://apitoken.sale/e/tool-result-missing · Идентично на api.anthropic.com и на этом шлюзе.

400 — нельзя задавать temperature и top_p одновременно

HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"`temperature` and `top_p` cannot both be specified for this model. Please use only one."}}

Почему возникает

• Оба параметра сэмплирования ушли в модель Claude 4. Фреймворки часто выставляют оба по умолчанию, так что в вашем коде их могло и не быть явно.
• Начиная с Claude Opus 4.7 — включая Opus 4.8, Opus 5 и Fable 5 — эти параметры убраны совсем, и отправка любого из них даёт 400.
• На Claude Sonnet 5 отклоняется значение, отличное от умолчания, а само умолчание принимается — поэтому один и тот же код может проходить на одном маршруте и падать на другом.

Что делать

• На Claude 4.x отправляйте не больше одного из двух.
• На Opus 4.7 и новее удалите оба, а также top_k. Замены нет: поведение задаётся промптом и параметром effort.
• Если temperature=0 стоял ради детерминизма — он никогда и ни на одной модели не гарантировал идентичный вывод.

Было и стало

# Before — 400
client.messages.create(model="claude-opus-5", temperature=0.7, top_p=0.9, …)

# After
client.messages.create(model="claude-opus-5", …)

Другие формы той же ошибки

• temperature and top_p cannot both be specified
• claude opus temperature removed
• bedrock claude temperature and topP error

Короткая ссылка: https://apitoken.sale/e/temperature-and-top-p · Идентично на api.anthropic.com и на этом шлюзе.

400 — max_tokens должен быть больше thinking.budget_tokens

HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"`max_tokens` must be greater than `thinking.budget_tokens`"}}

Почему возникает

• На моделях, которые ещё принимают фиксированный бюджет размышления, этот бюджет должен быть строго меньше max_tokens: размышление и ответ делят одно и то же окно вывода.
• На Claude Opus 4.7 и новее, а также на Sonnet 5 фиксированный бюджет убран вовсе — это проявляется другой 400 с указанием перейти на адаптивное размышление и параметр effort.

Что делать

• Поднимите max_tokens выше бюджета либо уменьшите бюджет.
• На актуальных моделях переходите на адаптивное размышление и управляйте глубиной через output_config.effort (low, medium, high, xhigh, max). Effort кладётся внутрь output_config, а не на верхний уровень.
• При включённом размышлении max_tokens ограничивает размышление и ответ вместе — бюджет, рассчитанный только на ответ, обрежет его на середине.

Актуальный вид

thinking={"type": "adaptive"},
output_config={"effort": "high"}

Другие формы той же ошибки

• max_tokens must be greater than thinking.budget_tokens
• "thinking.type.enabled" is not supported for this model
• "thinking.type.disabled" is not supported for this model
• budget_tokens removed claude

Короткая ссылка: https://apitoken.sale/e/thinking-budget-tokens · Идентично на api.anthropic.com и на этом шлюзе.

400 — префилл ответа ассистента не поддерживается

HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"This model does not support assistant message prefill. The conversation must end with a user message."}}

Почему возникает

• Диалог заканчивается сообщением ассистента, которым задают начало ответа. Это отклоняется на Claude Opus 4.6 и новее, на Sonnet 4.6 и новее и на Fable 5.
• Сообщения ассистента в других местах истории — например, few-shot примеры — по-прежнему допустимы. Отклоняется только последнее.
• Многие фреймворки делают префилл внутри себя, так что в вашем коде его может не быть явно.

Что делать

• Чтобы задать форму JSON, используйте структурированный вывод через output_config.format вместо префилла открывающей скобки.
• Чтобы получить метку классификации, опишите инструмент с перечислением допустимых значений.
• Чтобы убрать вступление, скажите об этом в системном промпте: отвечать сразу, без вводных фраз.
• Чтобы продолжить оборванный ответ, перенесите продолжение в пользовательский ход и процитируйте, на чём он остановился.

Другие формы той же ошибки

• This model does not support assistant message prefill
• claude prefill trailing whitespace error

Короткая ссылка: https://apitoken.sale/e/prefill-not-supported · Идентично на api.anthropic.com и на этом шлюзе.

400 — max_tokens выше потолка вывода модели

HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"max_tokens: 128001 > 128000, which is the maximum allowed number of output tokens for claude-opus-4-6"}}

Почему возникает

• max_tokens превышает потолок вывода конкретной модели. Этот потолок свой у каждой модели и не равен размеру контекстного окна.
• Конфигурация, написанная под одну модель, переиспользована с другой, у которой потолок ниже.

Что делать

• Смотрите потолок именно той модели, которую вызываете, а не общий.
• Примерно выше 16K токенов вывода отдавайте ответ потоком: большой непотоковый запрос может упереться в HTTP-таймаут SDK, даже когда сам max_tokens допустим.

Другие формы той же ошибки

• which is the maximum allowed number of output tokens
• claude max_tokens too large

Короткая ссылка: https://apitoken.sale/e/max-tokens-too-large · Идентично на api.anthropic.com и на этом шлюзе.

413 — запрос слишком большой

HTTP 413
{"type":"error","error":{"type":"request_too_large","message":"Request exceeds the maximum size"}}

Почему возникает

• Сериализованное тело превышает потолок размера. Обычная причина — картинки и PDF в base64.
• Base64 раздувает бинарные данные примерно на треть, поэтому файл, который на диске выглядит безопасным, на проводе выходит за лимит.
• Запрос может упереться в промежуточный потолок ниже задокументированного максимума, если приложено сразу много файлов.

Что делать

• Уменьшайте или пережимайте изображения до кодирования — большинству задач исходное разрешение не нужно.
• Большие документы загружайте один раз через Files API и ссылайтесь на file_id вместо пересылки байтов на каждом ходу.
• Подрезайте историю сообщений вместо дословного повтора всех ходов.

Другие формы той же ошибки

• claude api 413 request_too_large
• claude request exceeds the maximum size

Короткая ссылка: https://apitoken.sale/e/request-too-large · Идентично на api.anthropic.com и на этом шлюзе.

404 — модель или эндпоинт не найдены

HTTP 404
{"type":"error","error":{"type":"not_found_error","message":"model: claude-opus-4-5-20251101"}}

Почему возникает

• Несуществующий идентификатор модели: опечатка, дописанный к алиасу суффикс с датой или идентификатор, выведенный из обращения.
• Идентификаторы моделей пишутся через дефисы: claude-sonnet-4-6, но не claude-sonnet-4.6.
• Base URL, который уже заканчивается на /v1, из-за чего SDK собрал /v1/v1/messages.

Что делать

• Указывайте в base URL только origin и дайте SDK самому дописать /v1.
• Запросите список моделей, доступных ключу, вместо угадывания идентификатора.
• Замените выведенные модели: Claude 3.7 Sonnet и Claude 3.5 Sonnet — на claude-sonnet-5, Claude 3.5 Haiku — на claude-haiku-4-5, Claude 3 Opus — на claude-opus-5.

Список моделей, доступных ключу

curl https://api.apitoken.sale/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

Другие формы той же ошибки

• claude api 404 not_found_error model
• cursor model not found anthropic api key
• claude-3-5-sonnet 404

Короткая ссылка: https://apitoken.sale/e/not-found · Идентично на api.anthropic.com и на этом шлюзе.

403 — доступ запрещён

HTTP 403
{"type":"error","error":{"type":"permission_error","message":"Your API key does not have permission to use the specified resource."}}

Почему возникает

• Ключ действителен, но не имеет права на запрошенную модель или возможность.
• Региональное ограничение. Этот вариант часто приходит с более коротким телом вроде «Request not allowed» и касается того, откуда идёт запрос, а не самого ключа.
• В Anthropic API проблема с оплатой тоже может прийти как 403 — различать их нужно по типу ошибки, а не по статусу.

Что делать

• Ветвитесь по error.type, а не по одному статусу: тип отделяет проблему прав от проблемы оплаты.
• Попробуйте модель, доступ к которой точно есть, чтобы понять, здоров ли сам ключ.
• При региональной блокировке лечится точка выхода запроса, а не ключ. Этот шлюз принимает запросы из регионов, откуда апстрим напрямую недоступен.

Другие формы той же ошибки

• anthropic 403 Request not allowed
• claude api 403 forbidden country

Короткая ссылка: https://apitoken.sale/e/permission-denied · Идентично на api.anthropic.com и на этом шлюзе.

Для длинных операций требуется потоковая передача

HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"Streaming is strongly recommended for operations that may take longer than 10 minutes"}}

Почему возникает

• Непотоковый запрос сделан с таким max_tokens, при котором ответ может не уложиться в таймаут запроса.
• Чаще всего встречается в no-code и workflow-инструментах, где узел выставляет большой max_tokens, но не даёт переключателя потоковой передачи.

Что делать

• Отдавайте запрос потоком и забирайте итоговое сообщение через хелпер стрима.
• Если в вашем инструменте потока нет, уменьшите max_tokens до значения, которое укладывается в таймаут — примерно 16K токенов вывода это безопасный непотоковый потолок.

Поток и итоговое сообщение

with client.messages.stream(model="claude-opus-5", max_tokens=64000, …) as stream:
    message = stream.get_final_message()

Другие формы той же ошибки

• Streaming is required for operations that may take longer than 10 minutes

Короткая ссылка: https://apitoken.sale/e/streaming-required · Идентично на api.anthropic.com и на этом шлюзе.

402 — недостаточно баланса или достигнут лимит трат ключа

HTTP 402
{"type":"error","error":{"type":"invalid_request_error","message":"insufficient balance or key spending limit reached for this request"}}

Почему возникает

• Предоплаченного баланса не хватает на только что отправленный запрос.
• У ключа задан собственный лимит трат, и он достигнут, хотя на аккаунте баланс ещё есть.
• Большой max_tokens резервирует соответственно большое удержание заранее, поэтому запрос может быть отклонён, когда баланс ещё выглядит ненулевым. Неиспользованная часть удержания возвращается при закрытии запроса.

Что делать

• Пополните баланс или поднимите лимит трат у этого ключа.
• Уменьшите max_tokens до того, что реально нужно ответу: удержание считается от max_tokens, а не от фактически потраченных токенов.
• Смотрите актуальный баланс тем же ключом, которым делаете запросы.

Проверить баланс по ключу

curl https://api.apitoken.sale/balance \
  -H "x-api-key: $ANTHROPIC_API_KEY"

Другие формы той же ошибки

• claude api 402
• api key spending limit reached

Короткая ссылка: https://apitoken.sale/e/insufficient-balance · Такой ответ есть только у этого шлюза — в Anthropic API аналога нет.

400 — некорректный заголовок anthropic-beta

HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"invalid anthropic-beta header"}}

Почему возникает

• В заголовке anthropic-beta указан флаг, который этот шлюз не принимает, либо значение сформировано неверно.
• Несколько флагов соединены чем-то кроме запятой.
• Флаг скопирован из документации к возможности, которая с тех пор вышла из беты и больше не требует заголовка.

Что делать

• Несколько флагов отправляйте одним значением через запятую.
• Уберите флаги для возможностей, которые уже стали общедоступными — в их числе effort, потоковая передача аргументов инструментов и заголовок для 128K вывода.
• Если заголовок ставит сам SDK, не задавайте его ещё и вручную.

Другие формы той же ошибки

• anthropic-beta header error

Короткая ссылка: https://apitoken.sale/e/invalid-beta-header · Такой ответ есть только у этого шлюза — в Anthropic API аналога нет.

400 — не удалось разобрать тело запроса

HTTP 400
{"type":"error","error":{"type":"invalid_request_error","message":"Could not parse request body."}}

Почему возникает

• Тело не является валидным JSON: висящая запятая, строка в одинарных кавычках или переменная оболочки, развернувшаяся в неэкранированную кавычку.
• Отсутствующий или не-JSON заголовок Content-Type.

Что делать

• Проверяйте тело валидатором перед отправкой. Большинство таких запросов вообще не доходят до API в рабочем виде.
• В шелл-скриптах собирайте тело через heredoc или jq, а не конкатенацией строк.

Другие формы той же ошибки

• claude api could not parse request body

Короткая ссылка: https://apitoken.sale/e/invalid-request-body · Такой ответ есть только у этого шлюза — в Anthropic API аналога нет.

500 — внутренняя ошибка сервера

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

Почему возникает

• Непредвиденный сбой при обработке запроса. Ваши данные его не вызывали.

Что делать

• Ретрайте с экспоненциальной задержкой — SDK делают это для 5xx автоматически.
• Если ошибка держится для одного запроса, пока другие проходят, зафиксируйте идентификатор запроса и передайте в поддержку.

Другие формы той же ошибки

• anthropic api_error internal server error

Короткая ссылка: https://apitoken.sale/e/api-error · Идентично на api.anthropic.com и на этом шлюзе.

Не помогло?

Если запрос падает так, как здесь не описано, пришлите нам эндпоинт, маскированный идентификатор ключа, HTTP-статус и тело ответа. Полный ключ присылать не нужно никогда.

apiToken.sale отдаёт стандартный Anthropic Messages API, поэтому каждая не-шлюзовая ошибка здесь ведёт себя ровно так же, как против api.anthropic.com. Смотрите также гайд про лимиты и как направить SDK на свой base URL.