Убедитесь, что это 5xx, а не 4xx
Код 4xx требует правки запроса, ключа или баланса, и повторы там бесполезны. Код 5xx означает, что чинить у себя нечего, можно повторять.
Ошибки 500, 502, 503 и 504 в API: internal server error и как их пережить
Пятисотые коды означают сбой на стороне сервера, а не в вашем запросе. Разбираем, чем они отличаются, что повторять и как не сделать хуже.
/ Короткий ответ
Что это значит
Internal server error, то есть ошибка API с кодом 500, значит, что сервер получил корректный запрос и не смог его обработать из-за сбоя у себя. Соседние коды из той же семьи: 502 bad gateway, когда промежуточный узел не получил ответ от следующего, 503 service unavailable, когда сервис перегружен или на обслуживании, и 504 gateway timeout, когда узел ждал ответа и не дождался. У Anthropic перегрузка приходит как 529 overloaded_error, у DeepSeek как 503 Server is busy.
Общее у всех: ваш запрос, ключ и баланс ни при чём, менять в них ничего не надо. Отличие в том, что делать. 500 и 502 обычно кратковременны и проходят при повторе через несколько секунд. 503 и 529 говорят о перегрузке: повторять надо с растущей паузой, а при затяжном сбое переключить модель. 504 требует осторожности: сервер мог выполнить запрос, а ответ потерялся по дороге.
Правило для продакшена: повторять 5xx автоматически, не больше 3–5 попыток с паузой, растущей вдвое, а для запросов с побочными эффектами передавать ключ идемпотентности, чтобы повтор не создал дубль.
/ Почему
Откуда берётся ошибка
- 500 internal server error: необработанное исключение у поставщика. Чаще всего единичный случай, при повторе проходит.
- 502 bad gateway: прокси или балансировщик не получил ответ от сервера модели. Типично при выкатке новой версии или сбое одного узла.
- 503 service unavailable: перегрузка или обслуживание. У DeepSeek в пиковые часы это Server is busy, у Anthropic похожая ситуация приходит как 529.
- 504 gateway timeout: узел ждал ответа дольше своего лимита. Частая причина: длинная генерация без стриминга.
- Ошибка у провайдера модели за агрегатором: у OpenRouter это 502 Provider returned error, сбой не у агрегатора, а у того, кто обслуживает модель.
/ Коды
Что значит каждый код и что делать
| Код и текст | Причина | Что делать |
|---|---|---|
| 500 internal server error | Сбой на сервере поставщика | Повторить через 1–2 секунды, до 3–5 попыток |
| 502 bad gateway | Прокси не получил ответ от узла модели | Повторить с растущей паузой; если держится, сменить модель |
| 503 service unavailable / Server is busy | Перегрузка или обслуживание | Пауза 5–10 секунд, повтор, при затяжном сбое другая модель |
| 504 gateway timeout | Ответ не пришёл за лимит узла | Включить стриминг, укоротить запрос, повторять только идемпотентные |
| 529 overloaded_error (Anthropic) | Модель перегружена | Растущая пауза и повтор, запасная модель наготове |
Сроки пауз ориентировочные; если в ответе есть Retry-After, ждите столько, сколько в нём написано.
/ Что делать
Порядок действий
Включите повторы с растущей паузой
Официальные SDK умеют это сами: параметр max_retries, паузы удваиваются после каждой неудачи. Своих циклов повтора без ограничения попыток не пишите.
from openai import OpenAI client = OpenAI(base_url="https://api.kosareva.cloud/v1", api_key="KEY", max_retries=4, timeout=120)
Сделайте повтор безопасным
Запрос генерации текста повторять можно: он ничего не меняет. Запросы с побочными эффектами, например вызов ваших инструментов по результату, защищайте ключом идемпотентности или проверкой, не выполнено ли действие уже.
Держите запасную модель
Если 503 или 529 идут подряд дольше минуты, переключайтесь на другую модель того же класса: перегружена обычно одна, а не все сразу.
Включите стриминг для длинных ответов
При stream=true первый байт приходит быстро, и промежуточные узлы не обрывают соединение по таймауту, из-за чего и возникает 504.
/ По инструментам
Где это чинится в разных инструментах
- Python и Node.js SDK. Исключение InternalServerError для всех 5xx. С max_retries SDK повторит сам; ловите исключение только после исчерпания попыток.
- Cursor, Cline, Continue. Ошибка показывается в чате. Нажмите повтор через несколько секунд; если повторяется на каждом запросе, смените модель в настройках.
- n8n и Make. Включите Retry On Fail с паузой 5–10 секунд и 3–5 попытками. Для сценариев с записью в базу или отправкой писем проверьте, что повтор не создаст дубль.
- LangChain. with_retry() на модели или max_retries в конструкторе; для запасной модели есть with_fallbacks().
/ FAQ
Частые вопросы
Сколько раз повторять 5xx?
От 3 до 5 попыток с паузой, растущей вдвое: 1, 2, 4, 8 секунд. Больше обычно не помогает, лучше переключить модель.
Спишут ли деньги за запрос с ошибкой 500?
Как правило, нет: поставщики считают токены по обработанным запросам. При 504 запрос мог быть выполнен, поэтому сверяйте расход по ключу.
Чем 503 отличается от 429?
При 429 лимит ваш: слишком много запросов с вашего ключа. При 503 перегружен сам сервис, и ваш темп запросов ни при чём.
/ На kosareva.cloud
Как это выглядит у нас
Если у поставщика 5xx, наш шлюз пробрасывает код и тело ответа без изменений, повторы в SDK работают как обычно. Списание у нас по факту за токены, расход по каждому ключу виден в кабинете, поэтому после серии 504 легко проверить, что именно было выполнено. В каталоге /prices/ модели одного класса от разных поставщиков, и запасную модель на время сбоя можно выбрать по тому же ключу, не меняя base URL.
/ Дальше
Рядом в справочнике
Ключ, который работает из России
OpenAI-совместимый адрес, оплата в рублях, ключ сразу после регистрации. Пополнение картой от 50 ₽.