Errors

Все ошибки API возвращаются в едином формате с HTTP-статусом ≥ 400:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Недостаточно средств на балансе",
    "requestId": "req_01HX5Y3KJ8...",
    "timestamp": "2026-04-30T12:00:42.123Z"
  }
}

requestId — идентификатор запроса для саппорта. Сохраняйте его в логах: с ним мы быстрее найдём проблему.

HTTP-статусы

Код	Что означает
400 Bad Request	Неверные параметры запроса (см. code)
401 Unauthorized	Отсутствует или невалиден API-ключ
403 Forbidden	Ключ есть, но нет прав на ресурс
404 Not Found	Ресурс не существует или принадлежит другому пользователю
409 Conflict	Конфликт состояния (например, уже выполняется идемпотентный запрос)
422 Unprocessable Entity	Параметры провалили валидацию модели
429 Too Many Requests	Превышен лимит — см. Rate limits
500 Internal Server Error	Внутренняя ошибка
502 Bad Gateway	Провайдер модели недоступен
503 Service Unavailable	Сервис временно недоступен или в maintenance

Коды ошибок (error.code)

Аутентификация и авторизация

• UNAUTHORIZED — нет/невалиден ключ.
• API_KEY_REVOKED — ключ отозван.
• FORBIDDEN — нет прав.

Валидация

• VALIDATION_ERROR — параметры не прошли схему (детали в error.details).
• MODEL_NOT_FOUND — modelSlug не существует или модель деактивирована.
• INVALID_INPUT — параметр в недопустимом диапазоне для этой модели.

Биллинг

• INSUFFICIENT_BALANCE — баланс ниже стоимости запроса.
• BILLING_LOCKED — аккаунт заблокирован (свяжитесь с саппортом).

Лимиты

• RATE_LIMITED — превышен RPS-лимит. См. заголовок Retry-After.
• CONCURRENT_LIMIT — превышено число одновременных генераций (по умолчанию 5).

Провайдер

• PROVIDER_ERROR — общая ошибка провайдера.
• PROVIDER_TIMEOUT — провайдер не ответил за лимит времени.
• CONTENT_POLICY — промпт нарушает политику модели (NSFW, насилие и т.п.).

Идемпотентность

• IDEMPOTENCY_CONFLICT — тот же idempotencyKey использован с другим телом запроса.

Ретраи и автоматический refund

Если задача провалилась с финальной ошибкой провайдера (3 попытки worker исчерпаны), деньги автоматически возвращаются на баланс. Возврат отражается в BalanceLedger с типом REFUND. Идемпотентность гарантирует, что одна задача = одно списание + одно возможное возмещение.

Что делать с ошибкой

1. Логируйте requestId и code.
2. Для RATE_LIMITED и PROVIDER_TIMEOUT — повторите запрос с экспоненциальной задержкой.
3. Для CONTENT_POLICY, INVALID_INPUT, VALIDATION_ERROR — исправьте параметры.
4. Для INSUFFICIENT_BALANCE — пополните баланс.
5. Если непонятно — напишите в саппорт с requestId.