Ошибки и диагностика
Определяйте проблемы вызова по источнику ошибки и HTTP-статусу и выбирайте безопасное восстановление.
При ошибке API сначала сохраните HTTP-статус и обезличенное сообщение, затем определите, связана ли проблема с запросом, аутентификацией, моделью или сервером. Не повторяйте один запрос постоянно без выяснения причины.
Сначала защитите учётные данные и данные клиентов
Диагностические записи не должны содержать полный API Key, Header Authorization или x-api-key, Cookie, пароли, полный Prompt, файлы клиентов и другие чувствительные данные.
Определение источника ошибки
| Источник | Типичные признаки | Рекомендуемое действие |
|---|---|---|
| Содержимое запроса | Неверный JSON, отсутствующие поля, неверные типы или формат файла | Исправьте запрос по сообщению ошибки, не повторяя его без изменений |
| Аутентификация и права | API Key отсутствует, недействителен или не даёт доступа к модели | Проверьте Base URL, Header протокола, состояние Key и права на модель |
| Модель и ресурсы | ID модели, ID задачи или путь не существует | Скопируйте ID из каталога моделей и проверьте принадлежность ресурса учётной записи |
| Платформа или вышестоящий сервис | Временная недоступность, тайм-аут обработки или ошибка сервиса | Сохраните диагностику, ограниченно повторите; при постоянной ошибке остановитесь |
| Асинхронная задача | Ошибка после принятия, длительная обработка или недоступный результат | Сначала проверьте исходную задачу, не создавая её повторно |
Одна ошибка может содержать несколько признаков. Например, 404 бывает из-за неверного Endpoint, отсутствующей модели или задачи. Учитывайте итоговый URL и тело ошибки.
Краткий справочник HTTP-статусов
| HTTP-статус | Типичное значение | Рекомендуемое восстановление |
|---|---|---|
400 | Неверный формат, параметры или ввод | Исправьте запрос и отправьте заново |
401 | API Key отсутствует, недействителен или Header не соответствует интерфейсу | Проверьте аутентификацию протокола; при необходимости создайте и установите новый Key |
403 | Область доступа учётной записи, Key или модели не удовлетворяет запросу | Проверьте состояние учётной записи, ограничения токена и права на модель |
404 | Base URL, Endpoint, модель или задача не существует | Проверьте итоговый URL, ID модели, ID задачи и учётную запись владельца |
429 | Ограничена частота, параллелизм, квота или мощность сервиса | Прекратите частые запросы, снизьте нагрузку по фактической ошибке и повторите позже |
500–599 | Платформа, шлюз или вышестоящий сервис временно не выполняет запрос | Сохраните диагностику, используйте ограниченные повторы с увеличением интервала |
Эти статусы лишь помогают выбрать направление проверки. Программные коды ошибок различаются между протоколами и сервисами. Учитывайте HTTP-статус, фактическое тело ошибки и соответствующий API Reference.
Рекомендуемая диагностика
Зафиксируйте ошибку
Сохраните время и часовой пояс, Method, Path, ID модели, HTTP-статус и обезличенное сообщение ограниченной длины. Если ответ содержит Request ID, сохраните и его.
Проверьте адрес и аутентификацию
Используйте https://api.agtcloud.cn/v1 как Base URL и убедитесь, что итоговый URL не содержит повтор /v1/v1. OpenAI-совместимые интерфейсы обычно используют Authorization: Bearer your-api-key. Для других протоколов проверьте Header в соответствующем Reference.
Проверьте модель и запрос
Убедитесь, что ID взят из списка моделей, доступных учётной записи. Проверьте Content-Type, JSON, обязательные поля, типы файлов и размер ввода.
Оцените возможность повтора
Сначала исправьте 400, 401, 403 и явное отсутствие ресурса. При временных сетевых сбоях или 5xx допустимы ограниченные повторы с постепенным увеличением ожидания.
Подготовьте обезличенные сведения
Если проблема сохраняется, подготовьте минимальные шаги воспроизведения и диагностику. Не копируйте полный Key, клиентский Prompt, файлы или необезличенные ответы ради поиска ошибки.
Безопасные повторы
- Для обычных запросов чтения при временном сбое допустимы ограниченные повторы с увеличением интервала.
- Ошибки параметров, аутентификации и прав повторяйте только после устранения причины.
- Перед повтором создания задачи, внешнего инструмента или другого запроса с побочными эффектами проверьте, не выполнен ли исходный запрос.
- Для асинхронного запроса сначала проверьте исходный ID задачи; тайм-аут клиента не повод создавать дубликат.
- Ограничьте число повторов и общее ожидание. При постоянном сбое остановите автоматические запросы и сохраните диагностику.
Диагностические сведения
| Сведения | Пример или пояснение |
|---|---|
| Время | Дата, время и часовой пояс |
| Адрес запроса | Method и Path, без полного API Key |
| Цель вызова | ID модели; для асинхронной задачи также ID задачи |
| Результат | HTTP-статус и обезличенная ошибка |
| Особенности запроса | Streaming, инструменты, асинхронная задача |
| Среда клиента | Имя и версия SDK, версия среды выполнения, минимальные шаги воспроизведения |
| Трассировка | Request ID, если он есть в ответе |
Значения программных кодов и рекомендации см. в Справочнике кодов ошибок. Если проблема остаётся, см. Request ID и FAQ. При первом подключении ещё раз проверьте Быстрый старт и API Key, Base URL и аутентификацию.