Коды ошибок и диагностика

Унифицированный формат ошибок HTTP, каталог кодов и стратегии отказоустойчивости.

Если запрос не может быть успешно выполнен, SmallPict возвращает стандартный код ответа HTTP вместе со структурированным объектом JSON для удобной отладки.

Формат ошибки в JSON

JSON

{  "success": false,  "error": {    "code": "INVALID_IMAGE_PAYLOAD",    "message": "Переданный файл не является корректным изображением или поврежден.",    "details": {      "mime_type": "text/html",      "expected": [        "image/jpeg",        "image/png",        "image/webp",        "image/avif"      ]    }  }}

Таблица кодов ошибок HTTP

Код	Идентификатор	Причина	Решение
`400`	`BAD_REQUEST`	Некорректный JSON или неверные параметры.	Проверьте синтаксис JSON и имена полей.
`401`	`UNAUTHORIZED`	API-ключ отсутствует или отозван.	Проверьте заголовок `X-API-Key`.
`401`	`TIMESTAMP_DRIFT`	Смещение времени более ±300 секунд.	Синхронизируйте время сервера по NTP.
`401`	`INVALID_SIGNATURE`	Вычисленная подпись HMAC-SHA256 не совпадает.	Проверьте каноническую строку и Secret Key.
`403`	`FORBIDDEN`	У ключа недостаточно прав для этого ресурса.	Настройте разрешения ключа в личном кабинете.
`404`	`NOT_FOUND`	Задача (`job_id`) или ресурс не найдены.	Проверьте идентификатор в строке URL.
`413`	`PAYLOAD_TOO_LARGE`	Файл превышает максимальный размер для вашего тарифа.	Уменьшите размер файла перед отправкой.
`415`	`UNSUPPORTED_MEDIA`	Неподдерживаемый тип медиафайла.	Отправляйте только JPEG, PNG, WebP, AVIF или SVG.
`422`	`UNPROCESSABLE`	Файл имеет верное расширение, но поврежден.	Убедитесь, что файл загружен полностью.
`429`	`RATE_LIMIT_EXCEEDED`	Слишком много запросов в секунду.	Настройте повторы с Exponential Backoff.
`429`	`QUOTA_EXCEEDED`	Исчерпан месячный лимит трансформаций.	Повысьте тарифный план в панели управления.
`500`	`INTERNAL_ERROR`	Непредвиденный сбой серверов обработки.	Повторите запрос через короткое время.
`503`	`SERVICE_UNAVAILABLE`	Технические работы или временная перегрузка.	Временно используйте режим passthrough.