Устранение неполадок OpenAI-Compatible API: исправляем 401, имена моделей, потоковую передачу и base URL

Устранение неполадок OpenAI-compatible API становится гораздо проще, когда вы перестаете считать каждый неудачный запрос «провайдер недоступен». Большинство неудачных миграций связано с одним из шести уровней: ключом, base URL, семейством endpoint, именем модели, поведением streaming или billing/readback.

Flatkey помогает командам держать доступ к моделям, маршрутизацию, биллинг, аналитику использования и операционные контрольные механизмы в одном месте, но OpenAI-compatible клиент по-прежнему требует точной настройки. Запрос может выглядеть корректно в SDK и все равно завершаться ошибкой, потому что клиент указывает на неверный корень /v1, псевдоним модели относится к другому семейству endpoint, или stream буферизуется прокси-сервером.

Используйте это руководство по устранению неполадок OpenAI-compatible API как чистый путь отладки, прежде чем менять код приложения. Начните с curl, проверьте один нестриминговый запрос, затем добавьте SDK, после этого — streaming, tools и production traffic по одному уровню за раз.

Пятиминутный путь устранения неполадок OpenAI-compatible API

Прежде чем изучать код фреймворка, зафиксируйте минимальный запрос, который должен работать. Для Flatkey используйте base URL, указанный в вашей текущей консоли. На публичной главной странице Flatkey сейчас показан запрос к https://router.flatkey.ai/v1/chat/completions, что означает: SDK-клиентам обычно нужно передавать корень /v1 как base URL, а SDK должен добавлять /chat/completions.

export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-model-alias"

curl -sS "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {"role": "user", "content": "Reply with exactly: ok"}
    ]
  }'

Если этот запрос не проходит, проблема не в вашем app framework. Сначала исправьте ключ, base URL, семейство endpoint или псевдоним модели. Если он проходит, скопируйте те же значения в SDK и продолжайте отладку оттуда.

Самое быстрое правило устранения неполадок OpenAI-compatible API простое: не тестируйте streaming, tools, JSON mode, retries или полный agent workflow, пока не начнет успешно выполняться обычный нестриминговый текстовый запрос.

Читайте ошибку как уровень, а не как вердикт

Используйте код состояния, чтобы понять, что менять дальше.

Симптом	Вероятный уровень	Что проверить сначала
401, invalid_api_key или ошибка аутентификации	Ключ и auth header	Формат Bearer, источник ключа, случайно скопированные пробелы, ключ провайдера versus ключ gateway
403 или отказ в доступе	Аккаунт, проект или policy	IP allowlist, членство в проекте, одобрение модели, разрешение endpoint
404, model_not_found или неизвестная модель	Каталог моделей и семейство endpoint	Точный псевдоним модели, включенное состояние модели, /chat/completions versus /responses versus другой endpoint
400 malformed request	Структура payload	Обязательные поля, неподдерживаемые параметры, схема tools, формат сообщений
Stream подключается, но токены не появляются	Путь streaming	stream: true, SSE parser, buffering proxy, поддержка stream у endpoint
Запрос успешен, но usage отсутствует	Readback и billing	Сравнительный нестриминговый запрос, запись в dashboard, поведение финального stream event
429, 500, 502, 503 или 504	Rate, capacity или upstream	Backoff, объем запросов, status page, policy повторов, fallback route

В собственном руководстве OpenAI по ошибкам 401 рассматриваются как проблемы аутентификации, 429 — как проблемы rate или quota, а ответы 500/503 — как серверные состояния или перегрузка, допускающие повторную попытку. OpenAI-compatible gateway может добавлять собственные детали, поэтому сохраняйте тело ответа и request ID, когда эскалируете проблему.

Исправьте 401, прежде чем менять модели

401 — это самый частый обходной путь при устранении неполадок OpenAI-compatible API, потому что он выглядит как проблема модели или маршрута, хотя обычно это проблема аутентификации.

Проверьте это по порядку:

1. В запросе ровно один заголовок Authorization: Bearer ....
2. Ключ является ключом Flatkey, если вы обращаетесь к Flatkey, а не прямым ключом OpenAI, Anthropic, Google или test key.
3. В ключ не попали кавычки, перевод строки, невидимый префикс или пробел в конце.
4. Ключ загружается из окружения, в котором реально запускается процесс, а не только из вашей shell.
5. Аккаунт, проект, команда или IP policy разрешают этот route.

Используйте короткую shell-проверку, которая не выводит ключ:

test -n "$FLATKEY_API_KEY" && echo "key is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c

Если curl работает, а SDK возвращает 401, проверьте имена переменных окружения. Python client от OpenAI по умолчанию читает OPENAI_API_KEY, и Node client по умолчанию читает OPENAI_API_KEY. Если ваше приложение по-прежнему экспортирует OPENAI_API_KEY со старым прямым ключом провайдера, SDK может игнорировать ваш новый gateway key, если вы не передадите api_key или apiKey явно.

Исправьте base URL, не дублируя endpoint

Ошибки base URL обычно сводятся к двум шаблонам:

1. SDK получает полный endpoint, например https://router.flatkey.ai/v1/chat/completions, а затем снова добавляет /chat/completions.
2. SDK получает только домен, например https://router.flatkey.ai, и так и не достигает совместимого с OpenAI маршрута /v1.

Для Python передайте base_url или задайте OPENAI_BASE_URL. В официальном исходном коде Python-клиента также используется запасной вариант https://api.openai.com/v1, если пользовательский base URL не указан.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)

response = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[{"role": "user", "content": "Reply with exactly: ok"}],
)

print(response.choices[0].message.content)

Для Node передайте baseURL или задайте OPENAI_BASE_URL. В официальной документации Node-клиента baseURL описан как переопределение стандартного корня OpenAI API.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [{ role: "user", content: "Reply with exactly: ok" }],
});

console.log(response.choices[0]?.message?.content);

Если этот шаг устранения неполадок OpenAI-compatible API все еще не помогает, логируйте вычисленный base URL при запуске процесса. Не логируйте ключ.

Разделяйте имена моделей и семейства endpoint'ов

"Model not found" может означать, что alias указан неверно, но также может означать, что alias отправляется не в то семейство endpoint'ов. Модель, которая работает для chat completions, может быть недоступна через Responses, Messages, изображения, видео или embeddings с той же формой payload.

Перед переименованием моделей в production пройдите этот чеклист:

Проверка	Почему это важно
Подтвердите точный alias модели в текущей консоли Flatkey	Gateway-алиасы могут отличаться от маркетинговых названий у прямого провайдера
Подтвердите семейство endpoint'а	/v1/chat/completions и /v1/responses имеют разные форматы запроса
Удалите необязательные параметры	Неподдерживаемая опция может скрыть реальную проблему с моделью
Попробуйте короткий нестриминговый запрос	Обычный запрос отделяет маршрут от разбора потока
Запишите неудачное тело запроса и отметку времени	Поддержке и аудиту нужны точные модель, маршрут и ошибка

Внешняя документация OpenAI по моделям использует ту же идею для пользовательских endpoints: укажите URL endpoint'а, задайте model slug'и и выполните проверочный вызов. Относитесь к настройке gateway так же. Храните небольшой утвержденный map моделей в коде вместо того, чтобы позволять каждому сервису передавать строковые имена моделей напрямую.

Отлаживайте streaming после того, как non-streaming заработал

Streaming должен быть тестом второго этапа. В справочнике OpenAI Chat Completions возвращается либо JSON-объект chat completion, либо потоковая последовательность объектов chunk'ов chat completion. Responses API также поддерживает text/event-stream, когда включен stream.

Используйте прямую проверку stream:

curl -N "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from one to five slowly."}
    ]
  }'

Если нестриминговый запрос работает, а stream — нет, проверьте путь потока:

• Убедитесь, что ответ использует совместимый с SSE content type.
• Отключите middleware API-клиента, который буферизует весь ответ перед возвратом.
• Отключите буферизацию reverse proxy для этого маршрута.
• Проверьте, не ожидает ли ваш frontend-парсер chunk'и Chat Completions, тогда как ваш маршрут возвращает события Responses.
• Сверьтесь с существующим чеклистом streaming в Flatkey по адресу /blog/openai-compatible-streaming-sse-test.

Этот шаг устранения неполадок OpenAI-compatible API особенно важен в serverless и инструментах автоматизации. Некоторые wrappers возвращают успешный HTTP-статус, скрывая тот факт, что ни один токен не дошел до вызывающей стороны, пока stream не закрылся.

Добавляйте tools только после того, как базовый запрос работает без ошибок

Tool calling добавляет еще один уровень отказа. Gateway, маршрут или выбранная модель могут принимать обычные chat-сообщения, но отклонять схему tool, tool_choice, параллельные вызовы tools или строгие настройки структурированного вывода.

Используйте лестницу из трех запросов:

1. Простой текстовый запрос с той же моделью.
2. Тот же запрос с одной маленькой function schema.
3. Полная production schema для tools.

Если запрос 1 работает, а запрос 2 — нет, вы уже больше не отлаживаете auth или base URL. Вы отлаживаете возможности модели, семейство endpoint'ов или поддержку схемы. Удалите необязательные поля, сократите описания и проверьте, поддерживает ли выбранный маршрут модели нужное вам поведение tools.

Докажите корректность usage и billing readback

Не завершайте устранение неполадок OpenAI-compatible API на фразе «ответ вернул текст». Для миграции в production вам также нужно доказать, что запрос виден там, где его будут проверять команды финансов и эксплуатации.

После успешного smoke-теста зафиксируйте:

Доказательство	Что оно подтверждает
Временная метка и маршрут запроса	Какой путь шлюза принял трафик
Псевдоним модели	Какая настроенная модель была запрошена
Статус ответа и ID запроса	Что может отследить поддержка
Объект usage или количество токенов	Может ли приложение фиксировать драйверы стоимости
Снимок дашборда или биллинга	Может ли финансовая команда сверить расходы
Событие fallback или retry, если было	Изменила ли политика маршрутизации путь

Flatkey позиционируется вокруг одного ключа, прозрачного ценообразования, единого биллинга и дашборда для ключей, usage и маршрутизации. При миграции сочетайте инженерный smoke-тест с проверкой readback usage в консоли, прежде чем переводить реальный трафик.

Безопасный для production workflow устранения неполадок

Используйте эту последовательность, когда миграция на OpenAI-compatible API не работает:

1. Выполните один нестриминговый curl-запрос с текущим base URL из консоли, одним ключом и одним одобренным псевдонимом модели.
2. Исправьте любой 401 или 403 до изменения payload.
3. Исправьте составление base URL до изменения версии SDK.
4. Исправьте псевдоним модели и семейство endpoint до изменения политики retry.
5. Добавьте SDK с явным api_key или apiKey и base_url или baseURL.
6. Добавьте streaming и убедитесь, что клиент получает инкрементальные события.
7. Добавляйте tools или структурированный вывод по одной функции за раз.
8. Проверьте usage и readback биллинга.
9. Перенесите рабочие значения в конфигурацию, готовую к rollback.

Такой порядок не позволяет устранять неполадки OpenAI-compatible API методом догадок. Каждый шаг либо доказывает работу одного слоя, либо даёт вам более маленькую ошибку, которую нужно исправить.

Когда помогает Flatkey

Flatkey полезен, когда коренная проблема — операционная распылённость: слишком много ключей провайдеров, непоследовательный доступ к моделям, сложное для аудита usage и отдельные пути биллинга. Единый шлюз не убирает необходимость тестировать семейство endpoint, псевдоним модели, streaming, tools и readback биллинга, но он даёт команде одно место, где можно стандартизировать эти проверки.

Если вы мигрируете приложение, используйте этот гайд вместе с руководством Flatkey по миграции на OpenAI-compatible API по адресу /blog/openai-compatible-api-migration и чек-листом smoke-теста по адресу /blog/ai-api-smoke-test-checklist.

Когда будете готовы протестировать workflow с ключом Flatkey, начните с /sign-up и сделайте первый smoke-тест настолько небольшим, чтобы его можно было проверить вручную.

Часто задаваемые вопросы

Почему мой OpenAI-compatible API возвращает 401, когда ключ уже задан?

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

Должен ли base URL в SDK включать /chat/completions?

Обычно нет. Передайте SDK base URL /v1, а затем пусть SDK добавит endpoint. Передача полного endpoint часто создаёт дублирующиеся пути.

Почему модель работает без streaming, но ломается с stream: true?

Базовый маршрут может быть верным, а потоковый путь может блокироваться промежуточным buffering middleware, несовпадением SSE parser или комбинацией route/model, которая не поддерживает streaming. Проверьте с curl -N до отладки frontend-кода.

Почему возникает ошибка "model not found" при корректном имени модели?

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

Что нужно протестировать перед отправкой production-трафика?

Протестируйте один нестриминговый запрос, один запрос через SDK, один stream, один типичный вызов tool, если приложение использует tools, один путь ошибки и одну запись биллинга/readback. Затем сохраните rollback-конфигурацию для предыдущего маршрута провайдера.

Устранение неполадок OpenAI-compatible API — это не запоминание всех ошибок каждого провайдера. Это подтверждение пути от ключа к base URL, от base URL к семейству endpoint, от семейства endpoint к псевдониму модели и от успешного ответа к записи usage. Когда эти слои понятны, переключение трафика через Flatkey становится управляемой миграцией, а не ночной сессией отладки.