Коды ответов API: что значит каждый и что с ним делать
Девять разборов по кодам от 400 до 5xx и таймаутам. Главный вопрос на каждой странице один: повторять запрос или чинить причину.
Как читать код ответа
Код ответа HTTP говорит, кто виноват. Коды 4xx означают, что сервер получил запрос и отказал по понятной причине: неверный формат (400), неизвестный ключ (401), нет денег (402), запрещено для этого ключа или страны (403), нет такого пути или модели (404), слишком часто или кончилась квота (429). Коды 5xx означают сбой на стороне сервиса: 500 внутренняя ошибка, 502 шлюз не получил ответ от модели, 503 сервис перегружен. Отдельная группа: таймаут и connection error, когда ответа нет вообще.
Правило повторов простое. Повторять с растущей паузой можно 429, 500, 502, 503 и таймауты. Повторять 400, 401, 402, 403 и 404 бессмысленно: тот же запрос вернёт тот же код, пока не исправлена причина. Код уточняет тело ответа: у OpenAI поле type или code, у Anthropic error.type, у Gemini status. Смотрите на него раньше, чем на код.
Коды ответов: все разборы
Каждая страница: что значит, откуда берётся, порядок действий, где чинится в Cursor, Cline, n8n и SDK.
Ошибка 400 API
Запрос собран неверно: JSON, имена полей, max_tokens, формат messages.
Ошибка 401 API
Сервер не узнал ключ: missing authentication header, invalid api key.
Insufficient credits (402)
На счёте нет денег на этот запрос, даже если баланс не нулевой.
Ошибка 403 API
Ключ узнан, но действие запрещено: страна, план, модель, права ключа.
Unsupported country, region, territory
403 из России и что на самом деле помогает.
Ошибка 404 API
Нет такого пути или модели: base URL без /v1, опечатка в имени модели.
Rate limit exceeded (429)
Частота или квота, повторы с паузой, лимиты по уровням.
Ошибки 500, 502 и 503
Internal server error, bad gateway, service unavailable: когда повторять и как.
Таймаут и connection error
Запрос не дождался ответа или не соединился: где чинить, сколько ждать.
Частые вопросы
Код один и тот же, а тексты разные, на что смотреть?
На текст. Код 429 у OpenAI бывает и про частоту (rate_limit_exceeded), и про деньги (insufficient_quota), действия при них противоположные.
Почему SDK показывает не код, а название исключения?
Официальные SDK OpenAI и Anthropic заворачивают код в класс: AuthenticationError это 401, RateLimitError это 429, APIConnectionError это сеть или таймаут. Соответствие кодам одно и то же.
Сколько раз повторять 5xx?
Три-пять раз с паузой, которая удваивается от одной секунды. Если не помогло за минуту, это уже не сбой, а инцидент, и лучше переключить модель.
Другие разделы
Ключ, который работает из России
OpenAI-совместимый адрес, оплата в рублях, ключ сразу после регистрации. Пополнение картой от 50 ₽.