Ключ Anthropic выдаётся в консоли, консоль из России закрыта. Разбираем, как устроен API, что писать в заголовках и base URL, и как читать ответы 400, 401, 403, 429 и 529.
Anthropic API — это HTTP-интерфейс к моделям Claude по адресу https://api.anthropic.com: запрос уходит методом POST на /v1/messages с заголовками x-api-key (ваш ключ) и anthropic-version (дата версии протокола). Ключ вида sk-ant-… выдаётся в консоли Anthropic и привязан к организации с предоплаченным балансом.
Из России и регистрация в консоли, и привязка карты недоступны, а запросы с российских IP отклоняются с 403 permission_error. Поэтому у разработчиков из России два рабочих варианта: аккаунт и карта другой страны с VPN на каждый запрос или Anthropic-совместимый шлюз, где меняется только base URL и ключ, а формат запросов и SDK остаются те же.
Ошибки Anthropic приходят в JSON с полем type: authentication_error (401), permission_error (403), invalid_request_error (400), rate_limit_error (429), overloaded_error (529). Отдельный случай — текст Your credit balance is too low to access the Anthropic API: это 400, а не 402, и означает пустой баланс. Код ошибки по HTTP говорит, что делать: 401 и 400 чинить у себя, 429 и 529 повторять с паузой.
| Текст ошибки | Причина | Что делать |
|---|---|---|
| 401 authentication_error: invalid x-api-key | Ключ пустой, с опечаткой или не от Anthropic. | Проверить переменную окружения и заголовок x-api-key, пересоздать ключ. |
| 403 permission_error | Регион запроса не поддерживается или у ключа нет прав на модель. | Проверить IP, с которого уходит запрос, и доступ ключа к модели. Другой ключ с того же IP не поможет. |
| 400 Your credit balance is too low to access the Anthropic API | Баланс организации на нуле. | Пополнить баланс в консоли. Повторы бесполезны, хотя код 400. |
| 400 invalid_request_error | Неверный параметр: нет max_tokens, нет anthropic-version, неверный формат messages. | Прочитать message: там названо поле. Исправить запрос. |
| 429 rate_limit_error | Превышен лимит запросов или токенов в минуту. | Повторить с растущей паузой, уважать retry-after, сократить параллельность. |
| 529 overloaded_error | Модель перегружена на стороне Anthropic. | Повторить через 5–30 секунд, в SDK max_retries делает это сам. |
Поле type в JSON стабильно, текст message может меняться. Если ответ пришёл не в JSON, запрос не дошёл до API: проверьте base URL и прокси.
Anthropic требует два заголовка: x-api-key и anthropic-version. Без второго придёт 400 ещё до проверки ключа.
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-5","max_tokens":64,"messages":[{"role":"user","content":"ping"}]}'authentication_error — чинить ключ. permission_error — регион или права, ключ ни при чём. credit balance is too low — пополнять. rate_limit_error и overloaded_error — повторять.
SDK Anthropic и Claude Code читают ANTHROPIC_BASE_URL. Так один и тот же код работает и с api.anthropic.com, и с совместимым шлюзом без правок.
export ANTHROPIC_BASE_URL=https://api.kosareva.cloud export ANTHROPIC_API_KEY=ваш_ключ # Python from anthropic import Anthropic client = Anthropic() # base_url и ключ берёт из окружения
В официальных SDK параметр max_retries с экспоненциальной паузой уже есть. Для 400 и 401 повторы отключайте: они не пройдут.
Если карта российская, консоль Anthropic её не примет. Либо зарубежная карта и аккаунт, либо шлюз с оплатой в рублях. Проверьте это до того, как писать код.
Это адрес, куда SDK шлёт запросы; по умолчанию https://api.anthropic.com. Меняют его на адрес совместимого шлюза через ANTHROPIC_BASE_URL или параметр base_url, формат запросов при этом не меняется.
Так устроен API Anthropic: нехватка баланса считается ошибкой запроса. В коде ловите по тексту message или по BadRequestError и не повторяйте такой запрос.
Российскую карту консоль не принимает, а регистрация из России закрыта. Работают зарубежная карта с аккаунтом другой страны или шлюз с оплатой в рублях.
У нас Anthropic-совместимый адрес: для Claude Code и SDK достаточно ANTHROPIC_BASE_URL=https://api.kosareva.cloud и нашего ключа, модели называются claude-sonnet-5 и claude-opus-5. Запросы идут с российских IP без VPN, оплата в рублях: карта РФ или СБП от 50 ₽, юрлицо по счёту с договором и актом. Claude Sonnet 5 стоит 216 ₽ за миллион токенов на входе и 1080 ₽ на выходе, Claude Opus 5 — 540 и 2700 ₽; списание по факту, абонентской платы нет.
OpenAI-совместимый адрес, оплата в рублях, ключ сразу после регистрации. Пополнение картой от 50 ₽.