Понимание того, как API сообщает об ошибках, помогает быстро реагировать и поддерживать устойчивость вашей интеграции. API Fit It On делит ошибки на две отдельные фазы:
- Ошибки на уровне API: Запрос был отклонен немедленно до выдачи идентификатора предсказания.
- Ошибки выполнения: Запрос был принят, и идентификатор предсказания был возвращен, но генерация завершилась сбоем во время асинхронной обработки.
Ошибки на уровне API
Ошибки на уровне API возникают синхронно. Когда вы делаете POST запрос к /v1/run или GET запрос к /v1/status/{id}, сервер проверяет запрос перед началом любой интенсивной фоновой работы.
Если проверка не удалась, API возвращает статус ошибки HTTP (например, 400, 401), а JSON-ответ содержит сообщение error и конкретный строковый code.
{
"error": "Недопустимая полезная нагрузка запроса. Ожидалось { model_name, inputs }",
"code": "BadRequest"
}Стандартные коды ошибок
| Код | Ошибка | Причина | Как исправить |
|---|---|---|---|
| 400 | BadRequest | Неверный формат запроса или неподдерживаемое имя модели | Проверьте структуру JSON, убедитесь, что model_name указано верно, и проверьте, что все необходимые inputs предоставлены. |
| 401 | UnauthorizedAccess | Недействительный или отсутствующий ключ API | Убедитесь, что заголовок Authorization: Bearer YOUR_API_KEY верен и ключ активен. |
| 402 | OutOfCredits | Не осталось кредитов API разработчика | Пополните свои кредиты на панели управления Fit It On перед повторной попыткой. |
| 403 | Forbidden | Несанкционированный доступ к предсказанию | Вы пытаетесь проверить статус предсказания, созданного другим ключом разработчика. |
| 404 | NotFound | Предсказание не найдено | Убедитесь, что идентификатор предсказания верен при опросе конечной точки статуса. |
| 413 | PayloadTooLarge | Полезная нагрузка превышает лимиты | Убедитесь, что входные изображения не превышают 25 МБ и имеют разумное разрешение. |
| 500 | InternalServerError | Ошибка на стороне сервера | Повторите попытку с экспоненциальной задержкой. Обратитесь в службу поддержки, если проблема не исчезнет. |
[!TIP] Повторные попытки и идемпотентность Если вы столкнулись с ошибкой на уровне API, вы можете безопасно повторить тот же самый запрос после устранения проблемы. Поскольку запрос был отклонен немедленно, кредиты не были списаны, и риск дублирования обработки отсутствует.
Ошибки выполнения
Ошибки выполнения возникают после того, как API успешно принял ваш запрос и вернул идентификатор предсказания.
Поскольку модели генерации сильно асинхронны, вы обнаружите эти ошибки при опросе конечной точки /v1/status/{id}. Если фоновая задача завершается сбоем, конечная точка возвращает HTTP 200 OK (поскольку сам запрос на опрос был успешным), но поле status внутри полезной нагрузки будет "failed".
Ответ будет включать идентификатор предсказания и объект error, подробно описывающий, что пошло не так, включая категоризированное name и описательное message.
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "failed",
"output": null,
"error": {
"name": "ImageLoadError",
"message": "Не удалось загрузить входное изображение: URL вернул 404"
},
"created_at": "2024-05-15T12:00:00Z",
"updated_at": "2024-05-15T12:00:10Z"
}Распространенные ошибки выполнения
Большинство проблем выполнения попадают в несколько общих категорий для наших моделей:
| Категория | Типичные сообщения об ошибках | Как исправить |
|---|---|---|
| Ошибка загрузки изображения | Не удалось получить изображение, Недействительный URL изображения | Убедитесь, что предоставленные URL-адреса общедоступны без аутентификации. Для Base64 убедитесь, что он включает правильный префикс MIME-типа. |
| Проверка ввода | Разрешение изображения слишком мало, Отсутствует обязательный параметр | Убедитесь, что ваши входные данные соответствуют минимальным размерам и требованиям для конкретной модели. |
| Модерация контента | Обнаружен NSFW контент, Сработала блокировка безопасности | Замените или скорректируйте входное изображение или текстовую подсказку, чтобы соответствовать фильтрам безопасности. |
| Ошибка конвейера | Генерация не удалась, Ошибка сервера | Произошел непредвиденный сбой в кластере GPU. Повторите запрос с экспоненциальной задержкой. |
[!NOTE] Возврат кредитов при сбое Неудачные предсказания не расходуют кредиты. Если генерация завершается сбоем во время выполнения (например, из-за
Image Load ErrorилиPipeline Error), кредиты, списанные в начале запроса, автоматически возвращаются на ваш баланс разработчика.
Ошибки, специфичные для конечной точки
Некоторые модели имеют строгие, специфичные для рабочего процесса правила проверки, которые выполняются во время генерации:
- Управление позой: Завершится сбоем, если в целевом изображении не будет обнаружено человеческое тело.
- Виртуальная примерка: Завершится сбоем, если не сможет обнаружить действительный предмет одежды на изображении одежды.
- Генерация модели: Завершится сбоем, если предоставленное эталонное изображение лица не содержит четкого, беспрепятственного лица.
Если вы продолжаете сталкиваться с ошибками выполнения после приведения входных данных в соответствие с документацией, пожалуйста, свяжитесь со службой поддержки, указав свой идентификатор предсказания, чтобы мы могли провести расследование.