> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Как устранить ошибки API модели?
> Диагностика ошибок параметров, аутентификации, 429, 5xx, тайм-аутов, ресурсов и групп.
## Краткий ответ
Не диагностируйте запрос только по коду состояния HTTP. Сначала сохраните полную ошибку, имя модели, базовый URL, token-группу и идентификатор запроса, затем определите, является ли проблема **ошибкой конфигурации запроса** или **временным сбоем на стороне upstream**:
* `400`, `401`, `403`, неподдерживаемые параметры, блокировки безопасности и несоответствия групп обычно требуют изменения запроса или конфигурации. Повторная отправка того же запроса не устранит проблему.
* `429`, `503`, некоторые ответы `504` и `Upstream model timed out` могут быть вызваны нагрузкой на стороне upstream, доступностью ресурсов или длительным выполнением запросов. Проверьте журналы, затем используйте ограниченное число повторных попыток с экспоненциальной задержкой.
* Если сбой возникает только у одной модели или группы, проверьте авторизованную резервную группу. Если одновременно возникают сбои у нескольких моделей, сначала проверьте API-ключ, базовый URL и сетевой маршрут.
## Сохраните полную информацию об ошибке
На снимках экрана часто отсутствуют наиболее полезные поля. Перед устранением неполадок сохраните следующую информацию:
| Информация | Пример | Почему это важно |
| ------------------------- | ----------------------------- | ----------------------------------------------------------- |
| Статус HTTP | `400`, `401`, `429`, `503` | Определяет класс ошибки |
| Сообщение об ошибке и код | `Unsupported parameter: stop` | Позволяет определить детерминированные ошибки запроса |
| Модель и группа | `gpt-5.6-luna`, `Default` | Определяет затронутый маршрут |
| Базовый URL | `https://api.apiyi.com/v1` | Помогает проверить настройки эндпоинта и узла |
| ID запроса | ID, возвращаемый в ответе | Помогает службе поддержки найти запрос |
| Временная метка | Укажите часовой пояс | Помогает сопоставить записи вышестоящего сервиса и журналов |
| Запись в журнале | Наличие записи о списании | Показывает, началась ли генерация |
Никогда не публикуйте полный API key в обращении, на снимке экрана или в примере кода. Оставляйте только сообщение об ошибке, ID запроса и конфигурацию с удалёнными конфиденциальными данными.
## Устранение неполадок по типу ошибки
| Ошибка | Распространённая причина | Первое действие |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` или `Unsupported parameter` | Модель не поддерживает поле запроса, например `stop` в некоторых облегчённых моделях | Удалите неподдерживаемое поле и протестируйте минимальный запрос; не повторяйте запрос без изменений |
| `401 Invalid token` или `403` | Несоответствие API-ключа, базового URL, состояния token или разрешений группы | Проверьте API-ключ и базовый URL, затем проверьте группу token и разрешение для модели |
| `429` | Слишком большое количество параллельных запросов или перегрузка вышестоящей системы; сообщение также может скрывать проблему совместимости запроса | Прочитайте полную ошибку, уменьшите количество параллельных запросов и используйте экспоненциальную задержку; если проблема сохраняется, проверьте квоту и группы |
| `503` или `Service unavailable` | Временная недоступность, недостаток ресурсов вышестоящей системы или отсутствие доступного канала в группе | Немного подождите и повторите запрос ограниченное число раз; при необходимости используйте авторизованную резервную группу |
| `504` или `Upstream model timed out` | Длительная обработка вышестоящей системой, нестабильность вышестоящей системы или тайм-аут на каком-либо участке пути запроса | Проверьте журналы и тайм-аут клиента; убедитесь, что вы не используете узел CDN для длительного запроса |
| `RESOURCE_EXHAUSTED` | Временная нехватка вычислительных ресурсов или ресурсов для параллельных запросов вышестоящей системы | Уменьшите количество параллельных запросов, дождитесь восстановления или используйте другую доступную группу/модель |
| `rejected by the safety system` или `NO_IMAGE` | Запрос активировал политику безопасности контента вышестоящей системы | Измените промпт или входные данные; не отправляйте тот же запрос без изменений |
| Модель недоступна или группа не соответствует требованиям | token не включает требуемую группу, список разрешённых моделей блокирует её или имя модели указано неправильно | Проверьте основную группу token, резервную группу и разрешённые модели |
Один и тот же код состояния может иметь разные причины. Например, `429` может означать перегрузку вышестоящей системы, но также может указывать на проблему совместимости запроса, подробности которой отображаются только в полном сообщении об ошибке. Используйте тело ответа и журналы вызовов как окончательное подтверждение.
## Стандартные шаги устранения неполадок
Временно удалите необязательные параметры, определения tools, сложные входные изображения и длинные prompts. Оставьте только модель, обязательные сообщения и данные аутентификации. Это позволяет отделить ошибки запроса от ошибок маршрута или модели.
Убедитесь, что ключ API используется с базовым URL `api.apiyi.com`. В консоли проверьте основную группу token, резервную группу и разрешённые модели. Для некоторых моделей требуется выделенная группа.
Используйте повторные попытки с увеличивающейся задержкой для `429`, `503` и подтверждённых временных сбоев upstream-сервиса. При ошибках параметров, блокировках безопасности, недопустимых именах моделей и несоответствии групп измените запрос или конфигурацию, а не повторяйте запрос без изменений.
Генерация изображений, модели рассуждения и длинные текстовые запросы требуют более длительных тайм-аутов. Для длинных запросов используйте `api.apiyi.com` или `vip.apiyi.com` вместо узла CDN `api-cf.apiyi.com`, для которого действует ограничение примерно в 100 секунд.
Проверьте, была ли для запроса создана запись о списании. Тайм-аут или отключение клиента не всегда означает, что обработка на стороне сервера остановилась; не отправляйте запрос повторно вслепую, пока не подтвердите его статус.
## Минимальный тестовый запрос
Используйте следующий запрос, чтобы проверить эндпоинт, token и базовый вызов модели. Замените `YOUR_MODEL` на модель, доступную для вашего token, и не добавляйте необязательные поля, пока минимальный вызов не заработает.
```bash theme={null}
curl https://api.apiyi.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL",
"messages": [
{"role": "user", "content": "Reply with: test successful"}
]
}'
```
## Предотвращение повторяющихся ошибок
* Начните с минимального запроса, затем добавляйте `stop`, tools, параметры управления рассуждением, изображения и другие необязательные поля по одному.
* Ведите таблицу совместимости параметров для своих моделей вместо того, чтобы предполагать, что каждая модель поддерживает одни и те же поля.
* Не отправляйте сразу множество параллельных запросов после `429`; используйте экспоненциальную задержку и контролируйте количество параллельных запросов для каждой модели.
* Задавайте достаточный тайм-аут для запросов на генерацию изображений и рассуждение. Не сочетайте повторы SDK с собственными повторами на уровне бизнес-логики.
* Настройте резервную группу, протестированную с вашими фактическими рабочими параметрами.
## Часто задаваемые вопросы
Нет. `429` может быть вызвано числом параллельных запросов или перегрузкой вышестоящего сервиса, однако сообщение об ошибке также может скрывать проблему совместимости параметров. Прежде чем решать, уменьшить ли число параллельных запросов или изменить запрос, ознакомьтесь с полным текстом `error.message`.
Нет. Сначала убедитесь, что в запросе используется базовый URL APIYI, затем проверьте, не истёк ли срок действия token и выбрана ли правильная группа. Если только одна модель возвращает `Invalid token` наряду с ошибками 5xx или тайм-аутами, причиной также может быть маршрут вышестоящего сервиса.
Сначала проверьте журналы вызовов. Тайм-аут клиента означает лишь, что клиент прекратил ожидание; обработка на стороне сервера всё ещё может продолжаться. Если для запроса есть запись о списании, немедленный повтор может создать дублирующий вызов.
Не полагайтесь только на страницу ошибки. Проверка параметров, аутентификация и блокировки безопасности, которые не доходят до генерации моделью, обычно не создают итоговое списание, однако отключение клиента или запрос, обработка которого уже началась на стороне вышестоящего сервиса, всё ещё могут тарифицироваться. Используйте журналы вызовов как источник достоверной информации.
## Всё ещё не удаётся решить проблему? Обратитесь в поддержку
Если после выполнения описанных выше действий проблема сохраняется, обратитесь в поддержку APIYI через WeCom или по электронной почте. Чтобы ускорить устранение неполадки, укажите следующую информацию:
* Название модели, группу token и базовый URL
* Полное сообщение об ошибке, статус HTTP и ID запроса
* Время возникновения, включая часовой пояс `UTC+8`
* Минимизированный пример запроса или тело запроса с удалёнными конфиденциальными данными
* Содержат ли журналы вызовов запись о списании средств
Никогда не отправляйте полный API-ключ. Оставляйте видимыми только префикс и несколько последних символов, а остальные данные заменяйте.
Отсканируйте QR-код или нажмите на эту карточку, чтобы напрямую связаться с поддержкой.
Ошибки моделей, тайм-ауты, группы и вопросы тарификации
**Поддержка**: [support@apiyi.com](mailto:support@apiyi.com)
Рекомендуем указать в теме письма «ошибка модели» и название модели.
## Связанная документация
Проверьте базовый URL, API key и настройки аутентификации
Узнайте о группах token, маршрутах upstream и резервных группах
Настройте тайм-ауты и узлы, а также изучите устранение проблем с длительными запросами
Ознакомьтесь с лимитами параллельных запросов для моделей и рекомендациями по ошибке 429
Узнайте об ошибках 5xx, повторных попытках и проверках тарификации
Используйте журналы вызовов, чтобы подтвердить, была ли тарифицирована заявка