Примечание автора: если curl работает, а клиент возвращает 401, 404, 400 или не может подключиться, проверьте сервис-прокси API по 7 пунктам в заданном порядке. В статье также есть таблица кодов ошибок и чек-лист для диагностики за 10 минут.
С одним и тем же ключом и одной и той же моделью запрос через curl возвращает 200, а в Cherry Studio, Chatbox, Cursor, Cline, Claude Code или Codex CLI появляется ошибка 401, 404, 400, тайм-аут или пустой ответ. В такой ситуации сначала проверьте настройки клиента, а не меняйте ключ. Если curl работает, значит, ключ действителен, а сеть доступна. Скорее всего, проблема в том, что клиент отправляет запрос не так, как вы ожидаете.
Рекомендуемый порядок проверки: Base URL → протокол и эндпоинт → заголовок авторизации → ID модели → тело запроса → сеть. Но прежде убедитесь, что клиент вообще загрузил изменённую конфигурацию. В этой статье мы разберём цепочку запроса по 7 пунктам: для каждого рассмотрим симптомы, причины, способы проверки и исправления. Цель — за 10 минут определить, где возникла проблема: в клиенте, шлюзе или на стороне вышестоящего сервиса.
Это не очередная статья о принципах работы API, а руководство по устранению неполадок, которому можно следовать шаг за шагом.
Почему curl работает, а клиент не подключается: как диагностировать сервис-прокси API
curl проверяет лишь небольшой участок цепочки: разрешение DNS, TLS-рукопожатие, доступность сети, действительность ключа и работу одного эндпоинта, к которому вы обратились вручную. Он не проверяет, прочитал ли клиент изменённую конфигурацию, как он формирует Base URL и совпадают ли заголовки и тело его запроса с запросом curl.
Запрос от клиента проходит примерно такой путь: конфигурация клиента (переменные окружения, файл конфигурации, GUI) → формирование Base URL → протокол и эндпоинт → заголовок авторизации → ID и сопоставление модели → тело запроса (сообщения, инструменты, мультимодальный контент, потоковый режим) → прокси, TLS, сеть → шлюз → вышестоящая модель. Успешный запрос через curl означает лишь, что сработал путь, который вы задали вручную. Клиент вполне может использовать другой.
| Что проверить | Типичный симптом | С чего начать |
|---|---|---|
| 1. Чтение конфигурации | Изменения не действуют, ошибка осталась прежней | Посмотреть фактический URL запроса в логах клиента |
| 2. Формирование Base URL | 404, в пути появляется /v1/v1 или // |
Сравнить URL из логов с URL запроса curl |
| 3. Протокол и эндпоинт | 404, 400, ошибка разбора ответа | Уточнить, какой протокол использует клиент |
| 4. Заголовок авторизации | 401, хотя с curl ключ работает | Сравнить заголовки запросов |
| 5. ID модели | 404 или 400, сообщение о том, что модель не существует | Посимвольно сверить ID со списком моделей шлюза |
| 6. Тело запроса | Текстовый запрос проходит, но при добавлении изображения или инструмента возникает ошибка 400 | Добавлять параметры по одному и воспроизводить ошибку |
| 7. Сеть и потоковый режим | Тайм-аут, stream disconnected, пустой ответ | Отключить потоковый режим и сравнить результаты, проверить прокси |
Диагностика сервиса-прокси API, пункты 1–2: загрузка конфигурации клиента и формирование Base URL
Пункт 1: использует ли клиент изменённую конфигурацию
Симптомы: вы изменили Base URL и API-ключ, но ошибка осталась прежней. Или в одном проекте всё работает, а в другом — нет.
Причина: у большинства клиентов несколько источников конфигурации. Например, настройки в интерфейсе могут переопределять переменные окружения; в конфигурационном файле может быть несколько профилей, и активен не тот, который вы изменили; настройки проекта могут иметь приоритет над глобальными. Ещё одна возможная причина — старый процесс не завершился и по-прежнему использует значения, загруженные при запуске. Последнее особенно часто случается с инструментами командной строки: вы меняете переменные окружения в терминале, но уже запущенный процесс IDE или агента их не видит.
Как проверить: откройте логи клиента или отладочный вывод и убедитесь, что URL запроса и первые символы API-ключа совпадают с новыми значениями. Если логи смотреть неудобно, можно намеренно указать заведомо неверный Base URL и проверить, изменится ли ошибка. Так вы поймёте, вступили ли настройки в силу.
Как исправить: сначала выясните, в каком порядке клиент применяет настройки. Обычно настройки интерфейса или проекта имеют приоритет над глобальным конфигурационным файлом, а файл — над переменными окружения. Но правила зависят от клиента, поэтому сверьтесь с его документацией. Затем внесите изменения только в источник с самым высоким приоритетом, удалите конфликтующие значения в остальных местах и полностью завершите процесс клиента перед повторным запуском.
Пункт 2: завершающий слеш, повторение /v1 и префикс пути в Base URL
Симптомы: возникает ошибка 404, а в логах URL выглядит как /v1/v1/chat/completions, //chat/completions или /v1/chat/completions/chat/completions.
Причина: разные клиенты по-разному трактуют поле Base URL. Одним нужен корневой адрес, к которому они сами добавляют /v1; другим — адрес до /v1, после которого они добавляют /chat/completions. В некоторых клиентах Base URL и полный endpoint указываются в отдельных полях. Если целиком вставить https://api.apiyi.com/v1/chat/completions в поле, которое принимает только префикс, или добавить слеш к адресу, уже содержащему /v1, итоговый путь может получиться неверным.
Как проверить: посимвольно сравните полный URL запроса из логов с URL, который вы используете в curl. Обратите внимание, сколько раз встречается /v1, нет ли двойных слешей и лишних сегментов пути в конце.
Как исправить: заполните поле согласно документации клиента. В клиентах, совместимых с OpenAI, обычно указывают https://api.apiyi.com/v1 без слеша в конце. Если клиент автоматически добавляет /v1, уберите /v1, указанный вручную. После изменения ещё раз проверьте URL в логах: итоговый путь должен иметь стандартный вид, например https://api.apiyi.com/v1/chat/completions.
🎯 Рекомендация по настройке: адрес APIYI (apiyi.com) для подключения, совместимого с OpenAI, —
https://api.apiyi.com/v1. Он задаётся так же, как в официальном OpenAI SDK. Список доступных моделей можно посмотреть в консоли или получить через API списка моделей, используя тот же Base URL. Сначала убедитесь с его помощью, что API-ключ и адрес указаны верно, а затем настраивайте клиент.
Диагностика сервиса-прокси API, пункты 3–4: конечные точки протокола и заголовки авторизации
Пункт 3: соответствуют ли протокол и конечная точка друг другу
Симптомы: Base URL выглядит правильно, но запрос всё равно возвращает 404 или 400. Либо запрос проходит успешно, но клиент сообщает, что не может разобрать ответ, или возвращает пустое содержимое.
Причина: популярные API больших языковых моделей используют разные протоколы. Например, клиент поддерживает только Chat Completions, а вы направили его на конечную точку, где доступен только Responses. Claude Code использует протокол Anthropic Messages, а не OpenAI Chat Completions. У нативного формата Gemini и формата, совместимого с OpenAI, пути и тела запросов тоже совершенно разные. В curl вы могли вручную указать правильную конечную точку, а клиент отправляет запросы по своему протоколу по умолчанию.
| Тип протокола | Типичный путь конечной точки | Где обычно используется | Способ авторизации |
|---|---|---|---|
| OpenAI Chat Completions | /v1/chat/completions |
Cherry Studio, Chatbox, Cline и многие другие клиенты | Authorization: Bearer |
| OpenAI Responses | /v1/responses |
Новые инструменты экосистемы OpenAI | Authorization: Bearer |
| Anthropic Messages | /v1/messages |
Claude Code и другие нативные инструменты Anthropic | x-api-key и anthropic-version |
| Нативный формат Gemini | Нативный API с именем модели в пути | Нативный SDK Gemini | Согласно официальной документации и документации шлюза |
Как проверить: посмотрите в логах клиента на последнюю часть пути запроса и определите, какой протокол он использует. Затем убедитесь, что выбранная конечная точка шлюза поддерживает этот протокол. Если в клиенте есть выпадающий список «Тип провайдера» или «Формат API», проверьте, что выбран нужный вариант.
Как исправить: убедитесь, что протокол клиента, Base URL и модель совместимы между собой. Для формата, совместимого с OpenAI, выберите провайдера типа OpenAI; нативные инструменты вроде Claude Code настройте для протокола Anthropic; если нужны нативные возможности Gemini, используйте формат Gemini. APIYI поддерживает как формат, совместимый с OpenAI, так и нативные форматы API Claude, Gemini и других сервисов. Точные адреса подключения для нативных форматов смотрите в документации на docs.apiyi.com — не пытайтесь составить путь по памяти.
Пункт 4: соответствуют ли заголовки авторизации протоколу
Симптомы: возникает ошибка 401, хотя тот же Key отлично работает в curl.
Причина: в интерфейсах, совместимых с OpenAI, обычно используется Authorization: Bearer <Key>; в нативном API Anthropic — x-api-key и anthropic-version. Некоторые платформы также требуют заголовки с данными организации или проекта. В curl вы указали правильные заголовки, а клиент мог отправить другие, соответствующие другому протоколу, либо добавить заголовок организации, который шлюз не распознаёт. В результате авторизация не проходит.
Как проверить: сравните заголовки запросов в curl и логах клиента, обратив особое внимание на поля Authorization, x-api-key, Content-Type, OpenAI-Beta и другие. Проверьте, нет ли до или после Key лишних пробелов, переносов строки или кавычек — такое часто случается при копировании с веб-страницы.
Как исправить: заголовки авторизации должны соответствовать протоколу. Если протокол выбран правильно, большинство клиентов автоматически отправят нужные заголовки. Если клиент позволяет настраивать заголовки вручную, удалите ненужные заголовки организации или проекта. Заново вставьте Key и убедитесь, что в нём нет лишних символов.
Диагностика сервиса-прокси API, пункты 5–7: ID модели, тело запроса и потоковая передача
Пункт 5: ID модели и сопоставление моделей
Симптомы: ошибка 404 или 400 с сообщением, что модель не существует или указана неверно. Либо одна модель не работает, а остальные работают нормально.
Причина: ID модели должен в точности совпадать с ID в списке моделей шлюза. Различия часто бывают в регистре, суффиксе версии, формате префикса (например, provider/model) или псевдониме. Одна и та же модель может называться по-разному на разных платформах. Кроме того, нужного ID может не оказаться во встроенном списке клиента — тогда он незаметно подставит значение по умолчанию.
Как проверить: скопируйте ID модели из консоли или ответа API списка моделей шлюза и посимвольно сравните его с полем model в теле запроса из логов клиента. Если не работает только одна модель, сначала проверьте, соответствуют ли друг другу ID модели и эндпоинт, а затем — есть ли у аккаунта доступ к этой модели.
Как исправить: вручную добавьте пользовательскую модель в клиент и вставьте ID, предоставленный шлюзом, вместо того чтобы вводить его вручную. Если клиент выполняет сопоставление моделей, убедитесь, что итоговое имя указано правильно.
💡 Совет по ID моделей: если вы используете один ключ APIYI apiyi.com для вызова моделей OpenAI, Claude, Gemini, DeepSeek, Qwen и других поставщиков, сверяйте ID со списком моделей в консоли. На разных платформах одна и та же модель может называться по-разному, поэтому проще всего скопировать ID из консоли. Доступность моделей также проверяйте по консоли и документации.
Контрольная точка 6: тело запроса и мультимодальный формат
Симптом: обычный текстовый диалог работает, но при отправке изображения, вызове инструмента или включении параметров рассуждения возникает ошибка 400.
Причина: проблемы с совместимостью тела запроса обычно связаны со структурой мультимодального массива content, форматом поля image_url или отсутствием MIME-префикса вроде data:image/png;base64, у изображения в base64. Также формат полей для вызова инструментов может не соответствовать текущему протоколу; требования к max_tokens и max_completion_tokens различаются в зависимости от модели; параметры reasoning принимают только некоторые модели. Параметры разных поставщиков не всегда взаимозаменяемы.
Как проверить: добавляйте параметры постепенно. Сначала отправьте текстовый запрос, затем включите потоковую передачу, добавьте вызов инструмента и в последнюю очередь — мультимодальные данные. Проверяйте запрос после каждого изменения: поле, добавленное на этапе, где появилась ошибка, скорее всего, и вызывает проблему. В сообщении об ошибке обычно указано конкретное поле, поэтому проверьте ответ целиком.
Как исправить: отключите в клиенте ненужные расширенные параметры и настройте поля согласно документации целевой модели. Для изображений используйте корректный префикс base64 или доступный URL, а определения инструментов оформляйте по текущему протоколу.
Проверка 7: сеть, прокси, TLS и буферизация потоковых ответов
Симптомы: тайм-аут подключения, ошибка stream disconnected, пустой ответ после долгого ожидания либо успешный запрос без потокового режима и ошибка при его включении.
Причина: клиент может использовать системный прокси или прокси, заданный через переменные окружения, а curl — нет, или наоборот. Корпоративный межсетевой экран, проверка TLS-сертификатов, разрешение IPv6-адресов и DNS тоже могут помешать клиенту подключиться. В потоковом режиме некоторые прокси буферизуют ответ и пересылают его только после получения целиком. Не дождавшись данных, клиент сообщает о тайм-ауте или разрыве потока.
Как проверить: сначала определите, не установилось ли соединение вообще или поток был прерван. В первом случае ищите ошибки TLS или подключения, во втором обычно уже получена часть ответа. Отключите потоковый режим и повторите запрос: если без него всё работает, скорее всего, дело в буферизации на прокси или настройках тайм-аута. Проверьте, совпадают ли переменные окружения прокси у клиента и в терминале.
Как исправить: приведите настройки прокси клиента и curl к одному виду; исключите буферизующие прокси из маршрута потоковых запросов; при необходимости увеличьте тайм-аут клиента. Если вышестоящий сервис иногда обрывает соединение, можно настроить ограниченное число повторных попыток или временно переключиться на другую модель, чтобы проверить, связана ли проблема с конкретным провайдером.
Сервис-прокси API: быстрый старт, таблица ошибок и проверка настроек клиента
Получив ошибку, сначала определите её возможные причины по коду, а затем проверьте настройки клиента по списку.
Таблица кодов ошибок
| Код ошибки | Частые причины | Что проверить в первую очередь |
|---|---|---|
| 401 | API-ключ недействителен, истёк или отключён; неверный формат заголовка; не совпадает организация или проект | Пункты 1 и 4 |
| 403 | API-ключ действителен, но доступ запрещён политиками модели, организации или региона; IP не в белом списке; доступ к модели не включён | Пункт 5, права аккаунта |
| 404 | Неверный путь в Base URL; эндпоинт или ID модели не существует; маршрут не реализован в шлюзе | Пункты 2, 3 и 5 |
| 400 | Недопустимое тело запроса, параметры, ID модели или мультимодальные поля; несовместимые параметры провайдера | Пункты 5 и 6 |
| 429 | Превышен лимит запросов или исчерпана квота | Проверьте Retry-After, увеличьте интервал между попытками или переключитесь на другую модель |
| 500/502/503/529 | Ошибка шлюза или вышестоящего сервиса; 529 часто возникает при перегрузке | Ограничьте число повторных попыток, проверьте логи шлюза |
| Тайм-аут, stream disconnected | Сбой сети, прокси, TLS или вышестоящего сервиса | Пункт 7 |
Проверка настроек клиента
| Пункт | Что проверить |
|---|---|
| Источник настроек | Вы меняете переменные окружения, файл конфигурации или настройки в GUI? Что имеет наивысший приоритет? Не переопределяются ли настройки другим профилем или проектом? |
| Base URL | Содержит ли адрес /v1? Добавляет ли клиент /v1 автоматически? Нет ли лишнего слеша в конце? |
| Тип эндпоинта | Используется Chat Completions, Responses или нативный API Claude или Gemini? Поддерживает ли его версия клиента? |
| Заголовок авторизации | Используется Authorization: Bearer или x-api-key? Нужен ли anthropic-version? |
| ID модели | Точно ли он совпадает с записью в списке моделей шлюза, включая регистр и префикс? |
| Тело запроса | Содержит ли оно инструменты, изображения или параметры reasoning? Подходит ли поле max_tokens для выбранной модели? |
| Потоковая передача и сеть | Включена ли потоковая передача? Буферизует ли прокси ответ? Совпадают ли настройки прокси в клиенте и curl? |
Воспроизведение ошибки с минимальным запросом
Самый эффективный способ — сравнить запросы с одинаковыми параметрами: используйте один и тот же Base URL, API-ключ, модель и тело запроса. Сначала отправьте запрос через curl, затем — через клиент. Порядок действий:
- Проверьте API-ключ и Base URL через эндпоинт списка моделей, например отправьте запрос к
https://api.apiyi.com/v1/models; - Проверьте эндпоинт и ID модели с помощью минимального текстового chat-запроса;
- Включите потоковую передачу и проверьте сеть и прокси;
- Добавьте вызов инструментов или мультимодальные данные, чтобы проверить тело запроса;
- На каждом шаге проверяйте логи и клиента, и шлюза.
🚀 Совет по устранению неполадок: в консоли APIYI можно посмотреть статистику использования и подробные логи вызовов. Если клиент сообщает об ошибке, а в консоли нет записи об этом вызове, значит, запрос не дошёл до шлюза — проверьте настройки клиента или локальную сеть. Если запись есть и в ней указана ошибка, по логам можно определить, связана ли она с параметрами запроса или с вышестоящим сервисом.
Частые вопросы FAQ
Q1: Поможет ли смена ключа, если запрос через curl проходит, а клиент не подключается?
Обычно нет. Успешный запрос через curl уже подтверждает, что ключ действителен. Если смена ключа помогла, скорее всего, попутно был перезапущен клиент или переключён профиль, из-за чего конфигурация загрузилась заново. Вместо смены ключа полностью закройте клиент и запустите его снова, а затем проверьте в логах, какие Base URL и ключ он использует. В консоли APIYI можно проверить статус ключа и историю вызовов, чтобы убедиться, действительно ли проблема в нём.
Q2: Почему запрос к /models проходит, а chat-запрос — нет?
Эндпоинт списка моделей подтверждает только то, что аутентификация и Base URL в целом настроены правильно. Он не проверяет chat-эндпоинт, ID модели и тело запроса. Если chat-запрос не проходит, проверьте по порядку: соответствует ли протокол клиента эндпоинту (проверка 3), совпадает ли ID модели со значением в списке символ в символ (проверка 5), нет ли в теле запроса параметров, которые целевая модель не поддерживает (проверка 6).
Q4: Что проверить в первую очередь, если одна модель не работает, а с остальными всё в порядке?
Сначала проверьте ID модели и эндпоинт, затем — права доступа аккаунта. Чаще всего проблема в регистре, префиксе или псевдониме ID модели. Другая возможная причина — модель требует другого протокола, например нативного формата. И только после этого стоит проверять права доступа и доступность модели. В APIYI один ключ позволяет переключаться между моделями разных поставщиков. Временно выберите похожую модель для сравнительного теста — так можно быстро понять, проблема в одной модели или в общей конфигурации.
Q5: Как понять, проблема в клиенте или в шлюзе?
Обратите внимание на две вещи: получил ли шлюз запрос и проходит ли тот же запрос через curl. Если в журнале шлюза нет записи, проблема, скорее всего, в клиенте или локальной сети. Если тот же запрос через curl проходит, а через клиент — нет, дело, вероятно, в формировании запроса клиентом или в его теле. Если тот же запрос не проходит и через curl, а в логах отображается ошибка 5xx, стоит обратиться в поддержку шлюза.
Итоги: проверка сервис-прокси API за 10 минут и когда обращаться за помощью
Если curl работает, а клиент не подключается, не спешите менять ключ. Пройдитесь по этому списку — проверка займёт около 10 минут:
- Посмотрите логи клиента: найдите фактический URL запроса, заголовки и тело, убедитесь, что настройки применились;
- Проверьте Base URL:
/v1должен встречаться только один раз, без двойных слешей и повторяющихся сегментов пути; - Проверьте протокол эндпоинта: Chat Completions, Responses, Claude Messages или нативный формат Gemini — он должен соответствовать типу клиента;
- Проверьте заголовок авторизации:
Authorization: Bearerилиx-api-key. Удалите лишние заголовки организации и пробелы по краям ключа; - Проверьте ID модели: посимвольно сравните его со списком моделей на шлюзе;
- Отправьте минимальный запрос: с одним и тем же ключом, моделью и телом запроса отправьте его через curl и через клиент, затем сравните результаты;
- Включите потоковый режим: если запрос не проходит, проверьте буферизацию и тайм-ауты прокси;
- Добавьте инструменты или мультимодальные данные: если запрос не проходит, проверьте поля тела запроса;
- Определите источник проблемы: по логам шлюза выясните, в клиенте дело или в шлюзе.
Когда это баг клиента: на шлюзе нет записи о вызове либо curl успешно выполняет запрос с точно таким же URL, заголовками и телом, а клиент — нет. При этом вы уже убедились, что настройки верны и версия клиента поддерживает нужный эндпоинт. В таком случае обновите клиент или сообщите о проблеме разработчикам проекта.
Когда обращаться в поддержку шлюза: тот же минимальный запрос не проходит и через curl, а в логах шлюза видна запись о вызове с ответом 5xx. Другой повод — если одна и та же модель постоянно возвращает ошибку, а другие работают нормально, и вы уже исключили проблемы с ID модели и правами доступа. При обращении укажите время запроса, ID модели, код ошибки и сообщение из логов — так проблему найдут гораздо быстрее.
Для командных инструментов, которым важна стабильность, несколько моделей и маршрутов — это ещё и способ диагностики. Если одна модель или маршрут работает с ошибками, переключитесь на другой для сравнения: это поможет сразу определить масштаб проблемы. APIYI apiyi.com позволяет с одним ключом работать с форматом, совместимым с OpenAI, а также с нативными форматами Claude и Gemini. Проверить вызовы помогут данные об использовании и логи в консоли. Актуальные цены и доступность смотрите в консоли и документации.
Автор: техническая команда APIYI
Технические вопросы: свяжитесь с нами через главную страницу сайта APIYI
