Ответы, ошибки и повторы
HTTP-статусы, ошибки валидации и ограничения повторных запросов
Формат ответа
Многие операции возвращают JSON, но формат задаёт конкретный endpoint: файлы, PDF, ленты и потоковые ответы могут иметь другой Content-Type. Не вызывайте JSON-декодирование до проверки статуса и типа ответа.
Списки могут использовать page/limit, cursor или отдельные фильтры. Проверяйте схему операции: общий формат пагинации для всего API не предполагается.
Ошибки
Базовая ошибка содержит error. В части ответов дополнительно есть message и details для полей:
{
"error": "validation_failed",
"message": "Проверьте правильность заполнения полей",
"details": { "Email": "email" }
}Такая ошибка валидации возвращается с HTTP 422. Отдельные операции имеют собственные поля ошибок. Учитывайте статус и машинный код, если он предусмотрен; не сопоставляйте логику только с текстом сообщения.
| Статус | Действие |
|---|---|
400 | Исправить синтаксис, параметры или тело |
401 | Проверить сессию; при необходимости обновить токен один раз |
403 | Проверить права, блокировки, вертикаль и условия операции |
404 | Проверить маршрут, ID и доступность функции |
409 | Проверить состояние объекта и конфликт операции |
422 | Показать ошибки полей и исправить данные |
429 | Снизить частоту; учитывать Retry-After, если он присутствует |
5xx | Сохранить обезличенную диагностику и проверить сервис |
Повторы
Для чтения применяйте ограниченные повторы с увеличением задержки. Для создания заказа, оплаты, отправки сообщения и других изменений сначала выясните, применился ли предыдущий запрос.
Если операция поддерживает ключ идемпотентности, используйте её контракт. Не добавляйте произвольный заголовок в расчёте, что любой endpoint его обработает. Обновление токена не должно приводить к бесконечным повторам.