Прежде чем сообщать о баге

Если что-то не работает, самый быстрый способ выяснить — на вашей стороне проблема или на нашей — воспроизвести тот же запрос из другого инструмента.

Около 9 из 10 сообщений «API сломан» оказываются некорректным базовым URL, устаревшим API-ключом, неправильным именем модели или телом запроса из туториала, написанного три версии SDK тому назад.

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

Скопируйте эту curl-команду в терминал. Замените YOUR_KEY на ваш API-ключ из Dashboard и выполните её. Если вы получили нормальный ответ с завершением — ваш API-ключ, сеть и наш бэкенд работают исправно; значит, проблема в вашем клиентском коде или окружении.

cURL

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }'

Пошаговый чеклист

Ваш API-ключ действителен?

Откройте Dashboard → API Keys и убедитесь, что ключ совпадает с тем, который используется в вашем коде. Частая ловушка — пробел перед префиксом «sk-air-» после копирования и вставки.

Симптом: 401 Unauthorized.

Базовый URL указан верно?

Базовый URL должен быть https://api.airforce/v1 — не http, суффикс /v1 обязателен. В туториалах, написанных до появления пути v1 у OpenAI, он иногда опускается.

Симптом: 404 Not Found или curl зависает.

Имя модели написано правильно?

ID моделей чувствительны к регистру. Посетите страницу Models или выполните GET /v1/models, чтобы уточнить точный ID. Опечатка или устаревшая модель вернут понятную ошибку, а не «работает, но неверно».

Симптом: 400 unknown_model или 404 model_not_found.

Тело запроса сформировано правильно?

Chat-завершения используют массив messages. Изображения используют prompt + n. Аудио TTS использует input + voice. Отправка тела в формате chat на /v1/images/generations вернёт 400 — это легко пропустить при копировании фрагментов между разными документами.

Симптом: 400 с указанием проблемного поля в теле ответа.

Не превышен ли лимит запросов или квота?

429 = слишком много запросов в эту минуту. 402 = лимит плана или баланс исчерпан. Оба статуса отражаются в Dashboard. Запросы на бесплатном тарифе имеют отдельные лимиты от запросов на платном плане — платная модель может отвечать нормально, тогда как бесплатная ограничивает частоту.

Симптом: 429 Too Many Requests или 402 Payment Required.

Модель сейчас действительно доступна?

Проверьте страницу Models — перебои у провайдеров отображаются как «degraded» или «major outage». Если одна модель недоступна, а остальные работают, это проблема на стороне провайдера, которую мы обходим в роутинге, а не ошибка клиента.

Симптом: конкретная модель возвращает 5xx, тогда как другие работают.

Что означают HTTP-коды статусов

Каждый ответ с ошибкой содержит стандартный HTTP-код статуса. Понимание каждого из них избавляет от лишних тикетов.

Когда это действительно баг

Если curl-самопроверка выше работает, а точно такой же запрос из вашего кода — нет, проблема в вашем клиенте (или используемой им библиотеке). Если сама самопроверка завершается с 5xx или возвращает 4xx с сообщением, не соответствующим вашему запросу, — это стоит сообщить нам.

Как эффективно сообщить о проблеме

Откройте тикет поддержки из Dashboard или напишите в #support на Discord. Укажите:

• Полный HTTP-код статуса и тело ответа (а также заголовок cf-ray, если он присутствует).
• Приблизительную метку времени в UTC.
• Название модели и вызванный эндпоинт.
• Минимальный cURL, воспроизводящий проблему (замените реальный API-ключ на фиктивный!).
• Работает ли приведённая выше самопроверка на том же ключе.

Задайте вопрос в #support на Discord