Ошибки
Единый формат ошибок Clipia API, таблица HTTP-кодов и errorCode, а также какие из них можно безопасно повторять.
Все ошибки приходят в едином JSON-формате с полями type, code и человекочитаемым message. HTTP-статус задаёт класс ошибки, а машиночитаемый code — точную причину. Повторять с backoff можно только временные ошибки (429, 503); ошибки запроса (4xx) повторять без изменений бессмысленно.
Единый формат
Все ответы с ошибкой имеют одинаковую форму: объект error с полями type, code и message. Ветвите логику по машиночитаемому code, а HTTP-статус используйте как класс ошибки.
{
"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 |
Что повторять
Безопасно повторять с экспоненциальной задержкой можно 429, 500 и 503. Для 4xx-ошибок запроса (кроме request_in_progress) повтор без изменений вернёт ту же ошибку — сначала исправьте запрос.
Сообщения санитизированы
Поле message не содержит деталей внутренней инфраструктуры. Опирайтесь на машиночитаемый code, а не на текст message, который может меняться.