Ошибки

Формат

Все ошибки API — единый JSON:

{
  "error": {
    "code": "invalid_request",
    "message": "`model` and `prompt` are required",
    "type": "invalid_request"
  }
}

code — машиночитаемый, на него и завязывайся. message — пояснение для человека.

Коды HTTP-ответов

HTTP	code	Когда	Что делать
400	invalid_request	Кривое тело, неизвестное поле, неподдерживаемое значение, плохой референс	Исправить запрос. Не ретраить как есть
401	invalid_api_key	Нет заголовка / неверный или отключённый ключ	Проверить ключ
402	insufficient_credits	Не хватает кредитов	Пополнить баланс на dash.souz.ai
403	forbidden	Невалидная/истёкшая подпись ссылки на файл	Перезапросить GET /v1/jobs/{id} — там свежая ссылка
404	not_found	Джоба не найдена / чужая	Проверить ID
404	model_not_found	Чат: неизвестная модель	Список — GET /v1/models, каталог
410	file_expired	Файл удалён по сроку хранения (~24 ч)	Скачивать сразу; перегенерировать при необходимости
413	invalid_request	Тело чата больше 25 МБ	Сжать картинки
429	rate_limited	Превышен лимит запросов	Подождать Retry-After секунд, повторить
500	internal_error	Неожиданная ошибка на нашей стороне	Повторить позже; если повторяется — напиши нам
502	model_unavailable	Все провайдеры модели сейчас недоступны	Повторить позже или взять другую модель
502	storage_unavailable	Хранилище файлов временно недоступно	Повторить через минуту

Ошибки джоб (асинхронные)

Если генерация не удалась, джоба завершается status: "failed" с кодом в error.code, а резерв кредитов возвращается автоматически:

error.code	Значение
invalid_input	Провайдер отклонил вход (промпт/референс/параметры) — исправь запрос
content_blocked	Контент заблокирован политиками модели — переформулируй промпт
model_unavailable	Водопад провайдеров исчерпан — повтори позже
insufficient_credits	Не хватило кредитов на резерв

Правила ретраев

• Ретраить: 429 (после Retry-After), 500, 502, сетевые таймауты — с нарастающей паузой.
• Не ретраить без изменений: 400, 401, 402, 404, content_blocked, invalid_input.
• При ретраях создания джобы используй Idempotency-Key — иначе рискуешь создать (и оплатить) дубль. См. Джобы.