# Ошибки

## Формат

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

```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](https://dash.souz.ai) |
| 403 | `forbidden` | Невалидная/истёкшая подпись ссылки на файл | Перезапросить `GET /v1/jobs/{id}` — там свежая ссылка |
| 404 | `not_found` | Джоба не найдена / чужая | Проверить ID |
| 404 | `model_not_found` | Чат: неизвестная модель | Список — `GET /v1/models`, [каталог](/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` — иначе рискуешь создать (и оплатить) дубль. См. [Джобы](/jobs).