Коды ошибок и лимиты

В этом документе перечислены все ошибки, возвращаемые нативным API платформы. Суммы в примерах носят иллюстративный характер; актуальные ставки запрашивайте через GET /v1/prices.

Структура ответа с ошибкой

{ "error": { "code": 4001, "slug": "insufficient_funds",
             "message": "Required 1300000 SUN, available 420000 SUN",
             "field": null, "retryable": true,
             "details": { "required_sun": 1300000, "available_sun": 420000 } },
  "request_id": "req_01J9Z5P8T3WQ7X" }

Опирайтесь в программной логике на slug или code, а не на HTTP-статус — один и тот же статус может соответствовать совершенно разным ситуациям (например, статус 409 используется как для конфликта идемпотентности, так и для попытки отзыва неотзываемого заказа, при этом реакция приложения на них должна быть противоположной). Если вы встретили неизвестный код, обрабатывайте его по классу HTTP-статуса (4xx — ошибка на стороне клиента, не спамьте повторами; 5xx — временный сбой сервиса, повторите с задержкой).

Диапазоны кодов: 1000–1099 аутентификация и учетные данные · 1100–1199 лимиты частоты и квоты · 2000–2099 валидация параметров · 3000–3099 бизнес-состояние объектов · 4000–4099 баланс и биллинг · 5000–5099 поставка ресурсов · 9000–9099 внутренние ошибки.

Список кодов ошибок

Ошибки валидации (2000–2099) всегда имеют retryable: false и содержат имя проблемного поля в field; исправьте параметры запроса перед отправкой.

Гарантия безопасности поставки: код 503 при создании заказа является безопасным отказом (fail-secure) — заказ не сохранился и средства не списались, поэтому повтор с тем же client_order_id полностью безопасен. Если средства были списаны, но делегирование сорвалось (5002), деньги автоматически возвращены на баланс, а заказ завершен: создавайте новый заказ с новым id.

Политика повторных запросов (Retry policy)

Повторяйте запросы при кодах 429, 5xx, а также 4001/4002/4004 после устранения причины. Не повторяйте запросы с кодами 400, 401, 403, 404 и 409 (кроме 4004) — они требуют обязательной модификации запроса или исправления прав. Всегда передавайте client_order_id при создании заказов. Используйте экспоненциальную задержку от 250 мс со случайным разбросом (Full Jitter), ограничивая максимальную паузу 30 секундами и общее время ожидания 60 секундами. При наличии заголовка Retry-After всегда придерживайтесь указанного в нем времени.

Лимиты частоты запросов (Rate limits)

Лимиты действуют на каждый API-ключ, а также на IP-адрес источника. В заголовках каждого ответа возвращаются: RateLimit-Limit (лимит), RateLimit-Remaining (остаток) и RateLimit-Reset (секунды до сброса). Превышение возвращает 429, ошибку 1100 rate_limited и заголовок Retry-After.

Базовые лимиты на ключ (в секунду):

Следующие шаги

• Аутентификацияустранение ошибок 1xxx и синхронизация времени.
• Webhooksсобытие order.failed с полями failure.code и slug.
• Справочник по заказамкоды ошибок для каждого эндпоинта.