Ошибки и ограничения

Общий формат ошибки

Сбои аутентификации и ограничения частоты могут возвращаться на раннем этапе шлюзом или middleware:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authorization Bearer token is required"
  },
  "request_id": "..."
}

Пример ограничения частоты:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded, please try again later"
  },
  "request_id": "..."
}

Идентификатор модели не найден:

{
  "detail": "App not found: not_exists"
}

Модель не авторизована:

{
  "detail": "Model not allowed for this user"
}

Webhook не поддерживается:

{
  "detail": "webhook not supported"
}

Ошибка выполнения:

{
  "detail": "Runtime execution failed"
}

Неподдерживаемые возможности

Webhook

Webhook сейчас не поддерживается. Запросы с webhook-колбэками в теле, query-параметрах или заголовках отклоняются:

curl -X POST "${BASE_URL}/v1/queue/${ENDPOINT}" \
  "${COMMON_HEADERS[@]}" \
  -d '{
    "prompt": "a cinematic photo of a cat astronaut",
    "webhook_url": "https://example.com/hook"
  }'

400

{
  "detail": "webhook not supported"
}

Предупреждение

Текущая версия не предоставляет доставку колбэков. Используйте status_url для polling статуса задачи.

SSE stream

curl "${BASE_URL}/v1/queue/${ENDPOINT}/requests/${REQUEST_ID}/status/stream" ...

404

{
  "detail": "SSE streaming not supported"
}

Sync

Текущая мультимодальная очередь предоставляет только асинхронный протокол задач. Синхронного endpoint генерации нет.

curl -X POST "${BASE_URL}/v1/queue/${ENDPOINT}/sync" ...

404

{
  "detail": "Not Found"
}

Рекомендации по обработке

Сценарий	Обработка
Ограничение частоты	Повторяйте с backoff, учитывайте Retry-After
Ошибка queue task	После COMPLETED проверяйте error и error_type, не считайте завершение успехом
Ошибка parsing binary response	Используйте content_type из outputs, не полагайтесь на расширение файла

• Сохраняйте request_id после успешного создания задачи; он нужен для последующего polling, получения результата и отмены.
• При polling определяйте терминальность только по status; после COMPLETED проверяйте error, чтобы отличить успех от ошибки.
• Запрос response_url для незавершенной задачи может вернуть HTTP 202; не считайте это аномалией.
• При 404 Request not found не повторяйте слишком долго; обычно это неверный request_id, несоответствие endpoint или отсутствие доступа.
• Для 5xx / 502 используйте ограниченные повторы. Не повторяйте создание задач бесконечно, чтобы не создавать дубликаты.

Граница интеграции

Клиент должен опираться только на документированные поля queue-протокола: request_id, status_url, response_url, cancel_url, status, error, error_type и outputs. Недокументированные поля могут меняться без предупреждения.