Не повторять сразу
400/401/403/422 обычно требуют исправления данных, ключа или прав.
Ошибки
Ошибки API и что с ними делать
Все ошибки возвращаются в едином JSON-формате. В интерфейсе партнёра лучше показывать не технический код, а понятное действие: исправить данные, пополнить баланс, повторить позже или обратиться к администратору.
Формат ошибки
request_id всегда сохраняйте в логах: по нему поддержка RealIQ быстрее найдёт конкретный вызов.
{
"error_code": "insufficient_funds",
"message": "На балансе агентства недостаточно средств.",
"request_id": "req_1780000000_abcd"
}Таблица кодов ошибок
| HTTP | error_code | Причина | Что показать пользователю | Повторять? |
|---|---|---|---|---|
| 400 | invalid_check_input | Некорректные или неполные данные проверки. | Попросить исправить данные. | Нет, сначала исправить состав запроса. |
| 401 | unauthorized | API-ключ не передан или неверен. | Сообщить администратору интеграции. | Нет, пока не исправлен ключ. |
| 402 | insufficient_funds | Недостаточно баланса для боевого запуска. | Показать пополнение баланса. | Да, после пополнения. |
| 403 | scope_denied | У ключа нет права на метод. | Попросить выдать нужное право. | Нет, пока не изменены права. |
| 404 | not_found | Объект не найден или принадлежит другому аккаунту. | Проверить ID и API-ключ. | Нет, если ID неверный. |
| 409 | idempotency_conflict | Idempotency-Key повторён с другим телом. | Создать новый ключ идемпотентности. | Да, с новым Idempotency-Key. |
| 413 | document_too_large | Файл документа превышает лимит. | Сжать файл или разделить комплект. | Да, после изменения файла. |
| 422 | validation_error | Формат запроса не прошёл валидацию. | Показать ошибки полей в интерфейсе. | Нет, пока не исправлен payload. |
| 429 | rate_limit_exceeded | Превышен лимит запросов. | Показать ожидание и Retry-After. | Да, после указанной задержки. |
| 500 | internal_error | Внутренняя ошибка API. | Сохранить request_id и повторить позже. | Да, с увеличением задержки. |
| 503 | source_unavailable | Внешний источник временно недоступен. | Показать, что источник временно недоступен. | Да, позже или через мониторинг. |
Правило повторов
Повторять с задержкой
429/500/503 можно повторять с задержкой и ограничением числа попыток.
Не создавать дубли
Для боевых POST-запросов используйте Idempotency-Key, чтобы повтор не списал баланс повторно.