# Ошибки и лимиты

> Коды ответов, ошибки задач и лимиты запросов.

## Формат ответа

Каждый ответ — JSON вида `{"code", "msg", "data"}`. При ошибке есть ещё поле `error`. **Смотрите на `code` в теле** — HTTP-статус бывает 200 и при ошибке.

```json
{
  "code": 402,
  "msg": "Insufficient balance",
  "data": {
    "balance": "0.0100",
    "required": "0.0200",
    "topUpUrl": "https://ai.aimixmedia.site/cabinet/billing"
  },
  "error": "insufficient_balance"
}
```

## Коды ошибок

| code | error | Что значит | Что делать |
|---|---|---|---|
| 401 | `unauthorized` | Нет ключа, он неверный, отключён или удалён | Проверьте ключ |
| 402 | `insufficient_balance` | Не хватает денег | Пополните баланс |
| 403 | `account_blocked` | Аккаунт заблокирован | Напишите в поддержку |
| 404 | `task_not_found` | Нет такой задачи | Проверьте `taskId` |
| 409 | `idempotency_conflict` | `Idempotency-Key` уже использован с другим телом | Возьмите новый ключ |
| 422 | `validation_error` | Неверный параметр | Смотрите `msg` |
| 422 | `unsupported_model` | Нет такой модели | [Список моделей](https://docs.aimixmedia.site/models) |
| 429 | `rate_limited` | Слишком много запросов | Подождите `Retry-After` секунд |
| 500 | `internal_error` | Сбой у нас | Повторите позже |
| 505 | `model_disabled` | Модель временно отключена | Возьмите другую |

## Ошибки задач

Если задача создана, но не выполнилась, в recordInfo будет `state: "fail"` и код в `failCode`. Деньги возвращаются автоматически.

| failCode | Что значит |
|---|---|
| 501 | Модель не смогла или отказалась генерировать (причина в `failMsg`) |
| 504 | Слишком долго |
| 503 | Модель временно недоступна |
| 422 | Модель не приняла параметры (например, не скачалось фото) |
| 500 | Не удалось получить результат |

## Лимиты

| Что | Лимит |
|---|---|
| Создание задач и загрузка файлов | 20 запросов за 10 с на ключ |
| Чтение (recordInfo, list, balance) | 100 запросов за 10 с на ключ |
| Всего с одного IP | 300 запросов за 10 с |

Сверх лимита — HTTP 429 и заголовок `Retry-After`. Число одновременных генераций не ограничено: лишние задачи ждут в очереди. Нужно больше — напишите нам.