---
title: Ошибки
description: Единый формат ошибок Clipia API, таблица HTTP-кодов и errorCode, а также какие из них можно безопасно повторять.
---

Все ошибки приходят в едином JSON-формате с полями `type`, `code` и человекочитаемым `message`. HTTP-статус задаёт класс ошибки, а машиночитаемый `code` — точную причину. Повторять с backoff можно только временные ошибки (`429`, `503`); ошибки запроса (`4xx`) повторять без изменений бессмысленно.

<Callout type="info" title="Единый формат">
Все ответы с ошибкой имеют одинаковую форму: объект `error` с полями `type`, `code` и `message`. Ветвите логику по машиночитаемому `code`, а HTTP-статус используйте как класс ошибки.
</Callout>

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_credits",
    "message": "Недостаточно кредитов для генерации. Пополните баланс."
  }
}
```

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

| HTTP | `code` | Когда | Retry-able |
|------|--------|-------|------------|
| `400` | `invalid_request` | Невалидное тело или параметры | Нет |
| `401` | `invalid_api_key` | Ключ отсутствует, неверный или отозван | Нет |
| `402` | `insufficient_credits` | Не хватает кредитов на балансе | Нет — пополните баланс |
| `403` | `insufficient_scope` | У ключа нет нужного scope | Нет |
| `404` | `not_found` | Неизвестный `request_id` или `model` | Нет |
| `409` | `idempotency_key_reuse` | Тот же `Idempotency-Key` с другими параметрами | Нет — смените ключ |
| `409` | `request_in_progress` | Повторный запрос, пока первый ещё обрабатывается | Да — после завершения первого |
| `422` | `model_input_invalid` | Параметры не подходят модели | Нет — исправьте `input` |
| `429` | `rate_limit_exceeded` | Превышен лимит запросов | Да — после `Retry-After` |
| `500` | `internal_error` | Внутренняя ошибка | Да — с backoff |
| `503` | `service_unavailable` | Временно недоступно | Да — с backoff |

<Callout type="info" title="Что повторять">
Безопасно повторять с экспоненциальной задержкой можно `429`, `500` и `503`. Для `4xx`-ошибок запроса (кроме `request_in_progress`) повтор без изменений вернёт ту же ошибку — сначала исправьте запрос.
</Callout>

<Callout type="warn" title="Сообщения санитизированы">
Поле `message` не содержит деталей внутренней инфраструктуры. Опирайтесь на машиночитаемый `code`, а не на текст `message`, который может меняться.
</Callout>