Ошибки OpenAI API и диагностика лимитов: 401, 404, 429, 5xx (2026)

Ошибки OpenAI API выглядят пёстро, но сначала достаточно разделить пять уровней: ушёл ли запрос, верна ли идентификация, правильны ли адрес и модель, допустимы ли параметры, не упёрлись ли мы в лимит или квоту. При последовательной диагностике большинство проблем находится за несколько минут.

Разберём коды 401, 403, 404, 400, 429 и 5xx, приведём минимальные команды воспроизведения, стратегию повторов и единый порядок проверки. Названия моделей и настройки шлюза смотрите в разделе тарифов и в документации подключения.

Примечание: OpenAI, GPT и ChatGPT — товарные знаки соответствующих правообладателей. Примеры описывают типичное поведение интерфейсов по состоянию на октябрь 2026 года; коды ошибок и правила лимитов уточняйте в официальной документации и по фактическим ответам.

1. Сначала сохраните три доказательства

До начала диагностики сохраните:

HTTP-код состояния;
поля error.type, error.code, error.message в теле ответа;
заголовок x-request-id.

Request ID — самая полезная информация при общении с поставщиком. Без него можно сказать только «примерно тогда-то был сбой»; с ним можно найти конкретный запрос, конкретный upstream и конкретное списание.

Код	Частый тип	Первый вывод
400	`invalid_request_error`	Проблема в параметрах, JSON или длине контекста
401	`authentication_error`	Ключ отсутствует, неверен или отозван
403	`permission_error`	У ключа нет доступа к модели или проекту
404	`not_found_error`	Неверный Base URL или имя модели
429	`rate_limit_error` / `insufficient_quota`	Ограничение скорости или нехватка баланса
500/502/503/504	`server_error`	Сбой upstream или обрыв сети

2. 401 и 403: идентификация и права

Суть 401 — «сервер не признаёт этот ключ». Частые причины:

в заголовке нет Authorization: Bearer;
при копировании ключа добавились пробел, перевод строки или он был обрезан;
ключ удалён, перевыпущен или его проект отключён;
ключ шлюза отправлен на официальный адрес либо официальный ключ — на адрес шлюза;
в имени переменной окружения опечатка, и фактически отправляется пустая строка.

403 чаще означает «тебя узнали, но делать это не разрешают»: у ключа нет прав на модель, организация ограничена, в проекте не открыта нужная возможность. При 403 не повторяйте запрос многократно — сначала проверьте проект ключа и права на модель в консоли.

Быстрая самопроверка:

curl -sS "https://api.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -w "\nHTTP %{http_code}\n"

Если список моделей получен, ключ и адрес в основном верны. Если по-прежнему 401, проверяйте сам ключ и переменную окружения.

3. 404: адрес или модель не существует

404 не всегда означает «интерфейс отключён» — чаще это ошибка в пути. Типичные случаи:

Симптом	Причина	Действие
`404 page not found`	В Base URL лишний или недостающий `/v1`	Приведите к виду `https://api.zhongshangqihang.com/v1` по документации
`model_not_found`	Опечатка в имени модели или модель не открыта	Скопируйте имя со страницы тарифов
404, в пути двойной слэш	При сборке URL добавлен лишний `/`	Уберите повторный слэш
SDK возвращает 404	`base_url` и путь интерфейса дублируются	Оставьте только один `/v1`

Сначала отправьте минимальный запрос через curl, чтобы исключить проблему сборки URL в SDK. Если curl работает, а SDK нет, причина обычно в base_url, прокси или версии SDK.

4. 400: параметры и контекст

400 означает, что запрос недопустим, и повторять его бессмысленно. Частые причины:

ошибка JSON: висячая запятая, одинарные кавычки, неэкранированный перевод строки;
передан параметр, который модель не поддерживает, например некоторые модели не принимают отдельные параметры сэмплирования;
max_tokens превышает предел модели;
вход превышает окно контекста и возвращается context_length_exceeded;
формат, размер или URL изображения недоступны;
схема инструмента недопустима, отсутствуют обязательные поля.

Порядок действий: сначала сократите запрос до минимума, затем добавляйте параметры по одному. Не меняйте пять вещей сразу — иначе после исчезновения ошибки будет непонятно, что помогло.

5. 429: ограничение скорости или нехватка баланса

429 чаще всего понимают неправильно. У него как минимум два значения:

Код ошибки	Значение	Действие
`rate_limit_exceeded`	Превышены частота запросов, скорость токенов или параллельность	Снизить параллельность, поставить в очередь, включить экспоненциальную задержку
`insufficient_quota`	Недостаточно баланса или квота исчерпана	Пополнить, сменить ключ, проверить квоту проекта

Сначала смотрите тело и заголовки ответа. retry-after подсказывает, сколько ждать; x-ratelimit-remaining-requests и x-ratelimit-remaining-tokens показывают остаток. Если остаток равен нулю, долгая задержка не поможет — нужно дождаться сброса окна или повысить лимит.

Рабочий пример логики повторов:

import random
import time
from openai import OpenAI

client = OpenAI(
    api_key="sk-ваш-ключ",
    base_url="https://api.zhongshangqihang.com/v1",
)

def chat(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="gpt-5.5",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=500,
                timeout=60,
            )
            return resp.choices[0].message.content
        except Exception as exc:
            status = getattr(exc, "status_code", None)
            if status not in (429, 500, 502, 503, 504) or attempt == retries - 1:
                raise
            wait = min(2 ** attempt, 16) + random.random()
            print(f"{status}: повтор через {wait:.1f} с — {exc}")
            time.sleep(wait)
    raise RuntimeError("недостижимый код")

Повторы эффективны только для 429, 5xx и сетевых ошибок. Для 400, 401, 403 и 404 они лишь тратят время и квоту.

6. 5xx: сбой upstream и проблемы сети

500, 502, 503 и 504 обычно означают не ошибку в запросе, а сбой upstream, таймаут шлюза или обрыв сети. Принципы обработки:

Повторите один-два раза с экспоненциальной задержкой и случайным разбросом.
Для потоковых запросов проверьте, не получена ли уже часть ответа: частичный вывод мог быть тарифицирован.
Идемпотентные операции можно повторять автоматически; неидемпотентным нужен ключ дедупликации.
При массовых 5xx смотрите страницу статуса поставщика и не увеличивайте параллельность вслепую.
Записывайте request ID, чтобы поставщик мог найти запрос.

Если 5xx возникает только у вас, а у других команд всё нормально, проверьте размер тела запроса, таймауты и цепочку прокси.

7. Единый порядок диагностики

При ошибке идите по шагам, не пропуская:

Отправьте минимальный запрос через curl, проверьте адрес и ключ.
Сравните официальный адрес и адрес шлюза, убедитесь, что ключи не перепутаны.
Проверьте, что в Base URL остался ровно один /v1.
Проверьте, что имя модели скопировано со страницы тарифов и модель открыта.
Уберите необязательные параметры и добейтесь прохождения минимального запроса.
Проверьте баланс, квоту проекта и лимит ключа.
Изучите заголовки ответа 429 и различите ограничение скорости и нехватку баланса.
Посмотрите страницу статуса поставщика — нет ли сбоя upstream.
Сохраните request ID, код и тело ответа и только затем обращайтесь в поддержку.

8. Частые вопросы

429 всегда означает слишком частые вызовы?

Нет. 429 может означать превышение частоты или параллельности, а также нехватку баланса. Смотрите error.code и заголовки ответа; не снижайте скорость автоматически во всех случаях.

Достаточно ли при 401 заменить ключ?

Замена ключа исключает проблему самого ключа, но не поможет при перепутанных адресах, пустой переменной окружения или отсутствии прав у проекта. Сначала убедитесь, куда фактически ушёл запрос.

404 означает, что модель отключена?

В большинстве случаев это ошибка в Base URL или имени модели. Сначала вызовите /v1/models через curl, затем сверьте имя модели со страницей тарифов.

Можно ли повторять 5xx бесконечно?

Нет. Задайте максимальное число попыток и общий таймаут, чтобы не накапливать запросы во время сбоя. Для потоковых запросов учитывайте, что часть вывода могла быть тарифицирована.

Как отличить ошибку шлюза от ошибки официального API?

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

Что дальше

Сначала настройте минимальный запрос, логи использования и стратегию повторов, а уже потом подключайте бизнес-трафик. Если нужны пополнение в юанях и единый вход к нескольким моделям, начните с регистрации в ZSQH AI Gateway; имена моделей и цены смотрите в разделе тарифов.