Если запрос к Claude API возвращает API Error: 500, тип ошибки api_error и сообщение Internal server error, относитесь к этому как к уже возвращенной серверной ошибке API. Это не доказательство того, что сломан ключ, закончился баланс, испорчен prompt, заблокирован аккаунт или нужно немедленно менять провайдера.
Первая минута должна быть узкой. Откройте актуальный Claude Status, сохраните полный error body, request_id из JSON или request-id из response header, затем сделайте только короткий retry с jitter и жестким пределом. На этой фазе не меняйте model, endpoint, auth route, SDK, gateway route и тело запроса.
Статусная страница является сигналом с датой, а не окончательным диагнозом. В этом прогоне Claude Status был проверен 2026-05-02T13:51Z: публичный status API показывал all systems operational, но недавние resolved incidents все еще включали API и model-specific elevated-error события. Зеленый статус сужает ветку live incident, но не доказывает, что ваш конкретный путь уже восстановился.
60-секундная карта веток
Используйте эту карту до того, как начнете менять ключи, billing, prompt, timeout или провайдера. Если у вас есть HTTP status, error body и идентификатор запроса, значит вызов достиг API-слоя. Это отличается от сетевой ошибки, где нет ни status, ни body, ни request id.
| Точный сигнал | Считать это | Первое действие | Проверка того же пути | Следующая ветка |
|---|---|---|---|---|
500, api_error, Internal server error | Возвращенная серверная ошибка Claude API | Проверить status, сохранить request_id, коротко retry | Тот же model, endpoint, auth route и request body | Оставаться в ветке 500 |
529, overloaded_error | Перегрузка capacity | Проверить status, добавить jitter, снизить давление | Тот же путь после cooldown | Claude API 529 overloaded |
429, rate_limit_error | Rate limit, acceleration, quota или потолок route owner | Смотреть limit headers и активный credential route | Повторять только после окна или исправления маршрута | Claude API rate limit |
504, timeout_error | Timeout или слишком длинный запрос | Включить streaming, сократить ввод, разбить работу или вынести batch | Одна осознанная правка формы, затем проверка | Оставаться в timeout-ветке |
Нет status, body и request-id | Connection-layer failure | Проверить network, VPN, proxy, firewall, DNS, TLS, SDK timeout | Тот же payload после изменения одного сетевого фактора | Claude API connection error |
Терминал Claude Code показывает API Error: 500 | Поверхность Claude Code над API | Проверить /status, login/session, auth owner и route | Тот же терминальный путь после одной веточной правки | Claude Code API Error 500 |
| Gateway или provider route возвращает 500 | Route-owner или compatibility branch | Сравнить direct Anthropic и gateway без изменения prompt | Тот же prompt, model intent, timeout и размер входа | Сравнивать пути, не угадывать |
Полезный ответ узок: чистый Claude API Internal Server Error принадлежит ветке 500 api_error. Он может быть временным, но может повторяться только на одном model path, account route или request shape. Ваша задача не в том, чтобы сразу переписать интеграцию, а в том, чтобы не потерять доказательства, которые покажут, какой именно владелец у сбоя.
Что означает 500 api_error в Claude API
В API error reference Anthropic определяет HTTP 500 как api_error. Там же отдельно описаны 429 rate_limit_error, 504 timeout_error и 529 overloaded_error. Error response содержит error.type, error.message и request_id, а каждый API response также имеет request-id header.
Это официальное деление задает границы восстановления. Возвращенный 500 api_error означает неожиданный внутренний сбой API. Он не является штатным сообщением о billing, key ownership, account state или синтаксисе prompt. Эти владельцы проблемы должны иметь свои сигналы. Если API уже вернул api_error, сначала работайте с server-side branch и trace evidence.
request_id важнее, чем кажется. Скриншот с текстом Internal server error помогает человеку, но идентификатор запроса помогает support-команде или вашей платформенной команде найти конкретный вызов. Если SDK дает headers, сохраните request-id. Если JSON содержит request_id, сохраните его. Если нет ни того, ни другого, вы, возможно, не в ветке returned API error, а в ветке connection failure.
Не смешивайте 500 и 529. Оба могут выглядеть как проблема на стороне Anthropic, потому что интеграция перестает работать без локального релиза. Но client behavior разный. Для 529 нужно снижать давление, ставить очереди и избегать retry storm. Для 500 нужно проверить status, коротко повторить, сохранить identifiers и эскалировать, если тот же путь продолжает возвращать server error.
Не смешивайте 500 и 504. timeout_error указывает на длительность запроса, idle drop, streaming boundary или batch suitability. Для длинной работы Anthropic рекомендует streaming или Message Batches. Если точный тип ошибки timeout_error, меняйте форму запроса осознанно, а не продолжайте называть это Internal Server Error.
Безопасный recovery loop
Хороший recovery loop для 500 должен быть скучным и повторяемым. Сначала проверьте Claude Status и запишите время. Затем сохраните полный error body, response headers и request_id. После этого решите, можно ли безопасно повторять работу. Если вызов идемпотентен или защищен caller-side deduplication, сделайте короткий retry budget с jitter. Если вызов имеет side effects, сначала защитите бизнес-операцию от дублей.
Держите путь стабильным. Тот же model, тот же endpoint, тот же auth owner, тот же SDK или gateway, тот же request body и тот же timeout class. Это не догма ради чистоты. Это способ понять, восстановился ли тот же path. Если вы одновременно сменили model, ключ, prompt, gateway, retry policy и network route, успех после этих изменений не дает root cause.
Если статус показывает active API incident, не тратьте время на локальную хирургию. Зафиксируйте факт incident, остановите неважные повторы, поставьте background jobs в очередь и повторите тот же путь после обновления статуса. Если status зеленый, короткий retry budget все равно уместен, но он должен быть заранее ограничен: попытки, суммарное время и stop condition.
Если тот же путь успел восстановиться за одну-две попытки, пометьте это как transient server-side error и оставьте лог. Если тот же путь стабильно возвращает 500 api_error, остановитесь. На этой точке случайные изменения чаще ухудшают картину. Нужно собрать escalation packet или включить заранее продуманный degraded mode.
Не превращайте 500 в немедленный provider shopping. Gateway может быть полезен как временная production route или isolation comparison. Но смена route меняет владельца сигнала. Сначала сохраните оригинальный failure evidence, потом сравните direct Anthropic и gateway при той же форме запроса.
Production controls для повторяющихся 500
Ручной triage помогает оператору один раз. Production controls делают такую же дисциплину автоматической, когда ошибка приходит пачками.
Нужен retry budget, а не бесконечный цикл. Ограничьте attempts, elapsed time и concurrency. Добавьте jitter. Логируйте attempt number, backoff window и финальный результат. После инцидента сервис должен ответить, сколько вызовов восстановились retry, сколько упали окончательно и на каком path это произошло.
Разделите idempotent и non-idempotent work. Read-only classification, internal batch item, creation workflow и платежно-чувствительное действие не должны иметь одинаковый retry. Server error не всегда говорит, выполнилась ли часть downstream работы. Используйте request key, job id или бизнес-дедупликацию до повторов.
Добавьте circuit breaker для повторяющегося 500 api_error на одном route. Если error rate пересекает threshold, паузите non-urgent calls, очередите batch work и показывайте пользователю controlled degraded state. Для восстановления сначала отправьте маленький same-path probe, затем открывайте трафик постепенно.
Логи должны быть branch-aware. Минимальный набор: HTTP status, error.type, error.message, request_id или request-id, model, endpoint, SDK version, auth route, gateway route, request size class, retry count и timestamp. Не логируйте API keys, raw customer data, private prompts и полные environment dumps. Вам нужны trace handles, а не утечка данных.
Model switching должен быть product decision. Если один model path повторно возвращает 500, а другой model допустим для текущей задачи, временный fallback может быть разумным. Но назовите его degraded routing, сохраните evidence по исходному path и позже проверьте восстановление. Без этого команда начнет считать workaround полноценным diagnosis.
Разделение поверхностей и route owner
Фраза Claude API Internal Server Error часто появляется в смешанных средах. Прямой API, Claude Code, SDK exception, provider gateway, timeout и no-response connection failure могут выглядеть одинаково для человека, который видит только красную ошибку в логах.
Если видимая поверхность — Claude Code, используйте Claude Code branch. Claude Code действительно вызывает Claude API, но добавляет login state, resumed session, OAuth versus API-key ownership, shell environment variables, proxy rules и command diagnostics. Для терминала лучше начать с Claude Code API Error 500. Если симптом смешивает 500, 529 и 429, используйте Claude Code 500/529/rate-limit router.
Если поверхность — SDK exception, проверьте, был ли returned API status. Объект со status 500, headers и error body относится сюда. Исключение без HTTP status относится к no-response branch. Поэтому Claude API connection error начинается с границы request ID.
Если поверхность — gateway или provider route, сравнивайте, а не угадывайте. Запустите тот же prompt, model intent, input size, timeout class и environment через direct Anthropic, если такой доступ есть. Затем запустите gateway route. Если direct succeeds, а gateway fails, владелец может быть route mapping, provider capacity, credential ownership, proxy behavior или compatibility. Если оба пути возвращают 500, сигнал шире, но request identifiers все равно нужны.
Если exact error changed, смените branch. 529 overloaded_error — overload recovery. 429 rate_limit_error — limits and credential route diagnosis. 504 timeout_error — duration and request-shape recovery. No response — network, proxy, TLS, SDK timeout или route-owner diagnosis. Явные выходы экономят больше времени, чем один общий совет "try again later".
Escalation packet
Эскалируйте после короткого цикла: status проверен, request evidence сохранен, retry был ограниченным, тот же path все еще возвращает 500 api_error. На этом этапе больше случайных изменений обычно снижает качество evidence.
Пакет должен быть коротким: exact HTTP status и error type; полный error body с request_id или header request-id; timestamp и timezone каждой попытки; model, endpoint, SDK, SDK version и runtime; direct Anthropic, gateway, proxy или provider route owner; auth owner без секретов; request size class; streaming или non-streaming; retry count, backoff window, jitter behavior и final result; Claude Status result at the time; smallest redacted reproduction shape; одна фраза business impact.
Не превращайте пакет в data spill. Не отправляйте API keys, raw customer data, private prompts, full proxy logs или unredacted environment variables. Хороший packet доказывает branch и дает trace handles. Плохой packet заставляет support читать шум и создает риск утечки.
Same-path discipline делает эскалацию сильнее. "Было 500, потом мы сменили провайдера и стало лучше" — слабый сигнал. "Status green at 2026-05-02T13:51Z, same model and endpoint returned 500 api_error three times over a 40-second jittered budget, request IDs attached" — уже операционная картина.
FAQ
Claude API Internal Server Error — это то же самое, что 529 overload?
Нет. Anthropic определяет HTTP 500 как api_error, а 529 как overloaded_error. 500 требует returned-error handling, identifiers и короткого same-path retry. 529 требует pressure reduction, cooldown и защиты от retry storm.
Зеленый Claude Status доказывает локальную проблему?
Нет. Зеленый status — публичный сигнал на конкретное время. Он сужает active-incident branch, но не доказывает восстановление вашего model, endpoint, account route, region, SDK, gateway или request shape.
Нужно ли сначала менять API key?
Нет. Key rotation — слабое первое действие для returned 500 api_error. Работайте с ключами только при evidence для auth, key ownership, leakage или route mismatch.
Сколько retry безопасно?
Используйте budget, а не магическое число. Ограничьте attempts или elapsed time, добавьте jitter, повторяйте только work, который безопасно повторять. Для side effects сначала нужна deduplication.
Что делать, если ошибка в Claude Code?
Используйте Claude Code branch. Терминал добавляет login state, session state, OAuth/API-key routing, shell proxy variables и command diagnostics. Начните с /status и Claude Code API Error 500.
Что отправить support?
Status code, error.type, error.message, request_id или request-id, timestamps, model, endpoint, SDK version, route owner, retry timeline, status result и redacted reproduction. Чем меньше лишнего, тем быстрее виден 500 api_error branch.
Рабочее правило
Claude API Internal Server Error — это ветка восстановления 500 api_error, а не причина панически менять key, billing, prompt или provider. Проверьте live status, сохраните request identifiers, выполните короткий jittered retry, проверьте тот же path и эскалируйте только с чистым evidence.