13. Ошибки и справочник кодов

13. Ошибки и справочник кодов

Ошибки API приходят как `application/problem+json`:

Для поддержки сохраните `correlation_id` (он же `X-Correlation-Id`). Секреты и подписи в обращения не включайте.

| HTTP | `code` | Что значит и что делать | | --- | --- | --- | | 400 | `invalid_request` | Формат JSON, неизвестное или повторяющееся поле/параметр, неверный курсор. | | 400 | `invalid_amount` | Сумма не строка, не положительная или с лишней точностью для валюты. | | 400 | `invalid_idempotency` | `Idempotency-Key` не 8–128 допустимых символов. | | 400 | `invalid_query` | Параметры запроса не поддерживаются этим методом. | | 401 | `invalid_authentication` | Неверные ID магазина/ключа, формат заголовков, ключ отозван. | | 401 | `expired_signature` | Время вне окна ±5 минут. | | 401 | `invalid_signature` | Подпись не совпала. | | 401 | `nonce_reused` | Nonce уже использован. | | 403 | `insufficient_scope` | У ключа нет нужного права. | | 403 | `project_disabled` | Магазин выключен или архивирован. | | 404 | `not_found` | Объект не найден или принадлежит другому магазину. | | 405 / 415 | `method_not_allowed` / `unsupported_media_type` | Только `GET`/`POST`; для `POST` нужен `application/json`. | | 408 / 413 | `request_timeout` / `body_too_large` | Тело не получено за 5 секунд / больше 64 КиБ. | | 409 | `invalid_state` | Состояние объекта не допускает операцию (например, отмена оплаченного платежа). | | 409 | `conflict` | Заказ или ссылка с таким идентификатором уже существует. | | 422 | `method_unavailable` | Способ оплаты не включён для магазина/среды. | | 422 | `fee_below_method_minimum` | Комиссия магазина ниже минимума для включённых способов (3% СБП, 4% карты, 1% крипто). Обратитесь к менеджеру. | | 429 | `rate_limit` | Больше 180 запросов в минуту на ключ. Ждите `Retry-After`. | | 501 | `feature_unavailable` | Операция пока недоступна (например, `/conversions`). | | 503 | `live_not_enabled` | Боевой режим не включён. | | 503 | `service_unavailable` / `migration_required` / `service_unconfigured` | Сервис временно недоступен. Повторите с тем же `Idempotency-Key` и новой подписью. |

Возвраты и выводы добавляют свои коды (`refund_*`, `withdrawal_*`) — см. [8.4](#84-возвраты) и [8.5](#85-выводы-api).

Безопасные повторы

Если ответ потерялся (таймаут), не создавайте новый заказ. Повторите ту же команду с тем же `Idempotency-Key` и телом, со свежими `timestamp`, `nonce`, подписью. Затем прочитайте актуальное состояние `GET`-запросом.

---