Коды ответа (состояния) HTTP, которые может возвращать ЮKassa.
Код ответа HTTP | Код ошибки | Описание |
---|---|---|
200 | — | Запрос успешно обработан. Для POST и GET-запросов ответ содержит созданный, измененный или запрашиваемый объект в актуальном статусе. Для DELETE-запросов тело объекта пустое. |
400 | invalid_request | Неправильный запрос, нарушен синтаксис или логика запроса. Чаще всего этот статус выдается из-за нарушения правил взаимодействия по API. |
401 | invalid_credentials | Некорректные данные для аутентификации запроса (идентификатор и секретный ключ, OAuth-токен). |
403 | forbidden | Не хватает прав для совершения операции. |
404 | not_found | Запрашиваемый ресурс не найден. |
405 | — | Некорректный HTTP-метод запроса. Например, ошибка возникает при попытке отправить запрос на отмену платежа методом GET вместо POST. |
415 | — | Некорректный тип контента для POST-запроса. |
429 | too_many_requests | Превышен лимит запросов в единицу времени. |
500 | internal_server_error | Технические неполадки на стороне ЮKassa. Результат обработки запроса неизвестен. |
Если запрос обработан успешно, API вернет HTTP 200 и тело ответа с результатом выполнения запроса. Формат тела ответа зависит от запроса (подробнее в Справочнике API).
Пример ответа
HTTP/2 200 Server: nginx Date: Thu, 21 Apr 2022 07:39:21 GMT Content-Type: application/json;charset=UTF-8 Content-Length: 579 Signature: v1 29f31de9 1 MGUCMQCIu97XzcGGvH2C5C+4udkuX5xcS2qcgnSJqFRCZMKFSukrhBntD7dkzhTqYHErI60CMH1e48+07gTTd7YUIPZbZCwXL7d13qMR6hEJwi1CeSPLLZSvBChn3TkQzQY0dbyBRA== Strict-Transport-Security: max-age=15768000 { "id" : "29f31de9-000f-5000-a000-109987b98a6a", "status" : "pending", "amount" : { "value" : "2.00", "currency" : "RUB" }, "description" : "Заказ №1", "recipient" : { "account_id" : "152368", "gateway_id" : "459728" }, "created_at" : "2022-04-21T07:39:21.471Z", "confirmation" : { "type" : "redirect", "confirmation_url" : "https://yoomoney.ru/checkout/payments/v2/contract?orderId=29f31de9-000f-5000-a000-109987b98a6a" }, "test" : false, "paid" : false, "refundable" : false, "metadata" : { "order_id" : "37" } }
У некоторых объектов, например у платежей, есть статус. Он отражает результат выполнения операции. Например, если платеж создан, но пользователь еще не подтвердил его, объект платежа будет в статусе
pending
. Если оплата перечислена на баланс вашего магазина, статус объекта платежа будет succeeded
. Если по каким-то причинам не удалось провести платеж, то статус будет canceled
, объект платежа будет содержать данные о причинах отмены.Если в ответ на запрос вы получили объект в статусе
pending
, вам нужно дождаться, когда объект перейдет в финальный статус. Узнать об изменении статуса можно двумя способами:- Подписаться на входящие уведомления и дождаться уведомления. Подробнее о входящих уведомлениях
- Повторить запрос с теми же данными и с тем же ключом идемпотентности или запросить информацию об объекте методом GET. Если статус объекта не изменится, рекомендуется повторять запрос с возрастающим разумным интервалом (например, можно использовать последовательность Фибоначчи).
Если созданный объект должен был уже перейти в другой статус (например, закончилось время, отведенное на подтверждение платежа пользователем), а объект всё еще остается в статусе
pending
, обратитесь в техническую поддержку.Если запрос некорректный с точки зрения синтаксиса или логики API ЮKassa, API вернет HTTP 400. В теле ответа будет указана возникшая ошибка. Описание параметров тела ответа
Пример ответа
HTTP/2 400 Server: nginx Date: Thu, 21 Apr 2022 07:51:44 GMT Content-Type: application/json;charset=UTF-8 Content-Length: 238 Signature: v1 29f320d0 1 MGQCMHU++9/SylfnZ4u5PWfyGtjib5WsLId2Jy2OnsD7+evQpETko30oTuUNNXe79VaecgIwUmiabma6qGobOP8+5KfjblFdrXg91PcwbsOX/yEIsspGnZqBKS067ulHu0UUze93 { "type" : "error", "id" : "55a02ced-be5d-462d-a6fb-0ace18881671", "code" : "invalid_request", "description" : "Idempotence key is too long. Send the value in accordance with the documentation", "parameter" : "Idempotence-Key" }
Примеры ситуаций, в которых может возвращаться код ответа HTTP 400:
- отсутствуют обязательные параметры;
- ошибка в значении параметра (не тот формат, недопустимое значение);
- нарушена логика формирования запроса (например, нужно передать один из двух параметров, а переданы оба, или значение в одном параметре не соответствует значению в другом параметре);
- что-то не так с ключом идемпотентности.
Причина возникновения ошибки указана в теле ответа, в параметре
description
. При необходимости тело ответа содержит parameter
с названием параметра, из-за которого возникла ошибка.Поправьте ошибки и повторите запрос с новым ключом идемпотентности.
Если в заголовке запроса отсутствует параметр
Authorization
или с переданными данными для аутентификации что-то не так, API вернет HTTP 401. В теле ответа будет указана возникшая ошибка. Описание параметров тела ответаПример ответа
HTTP/2 401 Server: nginx Date: Thu, 21 Apr 2022 07:49:13 GMT Content-Type: application/json;charset=UTF-8 Content-Length: 202 WWW-Authenticate: Basic Signature: v1 29f32039 1 MGQCME00FWXiu+F4Jdj1vddlsiZrcEwNy3XaCoXPpJF+Fpth62D/Hxru2fWBIAMKNxaT5gIwKaUvlJg/Thj5B0mIbn8+NG4+vegpzpSUjnTRcDAxwJGve9bcj+gliWBbSeWSzZd/ { "type" : "error", "id" : "c7e8fadc-c21f-4074-b1ac-d85234eeca1d", "code" : "invalid_credentials", "description" : "Authentication by given credentials failed", "parameter" : "Authorization" }
Порядок действий зависит от вашего способа аутентификации запросов:
- HTTP Basic Auth (идентификатор магазина и секретный ключ);
- OAuth (OAuth-токен) — относится только к тем, кто использует API для партнеров.
Примеры ситуаций, в которых может возвращаться код ответа HTTP 401 при использовании HTTP Basic Auth:
- в запросе нет идентификатора или секретного ключа;
- идентификатор и секретный ключ указаны в неправильном порядке или формате;
- идентификатор не соответствует тому магазину, в который вы хотите провести операцию, или в идентификаторе опечатки;
- указанный секретный ключ неактуальный или содержит опечатки.
Причина возникновения ошибки указана в теле ответа, в параметре
description
. Поправьте ошибки и повторите запрос. Ключ идемпотентности можно использовать тот же или сгенерировать новый.Примеры ситуаций, в которых может возвращаться код ответа HTTP 401 при использовании OAuth-авторизации:
- вы не передали OAuth-токен;
- в токене есть опечатки;
- вы удалили приложение, для которого был выдан этот токен;
- токен устарел;
- пользователь отозвал токен.
Причина возникновения ошибки указана в теле ответа, в параметре
description
. Поправьте ошибки, при необходимости получите токен заново и повторите запрос. Ключ идемпотентности можно использовать тот же или сгенерировать новый.Если запрос корректный, но не хватает прав для совершения операции, API вернет HTTP 403. В теле ответа будет указана возникшая ошибка. Описание параметров тела ответа
Пример ответа
HTTP/2 403 Server: nginx Date: Wed, 20 Apr 2022 13:55:23 GMT Content-Type: application/json;charset=UTF-8 Content-Length: 281 Signature: v1 29f2248b 1 MGQCMEl6TymNwpekysxE+4ZmSze5gr2MxVolp+ZAZufDN3M+9z4mCQKvCFMQISDqubqQQwIwMr4tLc+QMYA5QnFjwK/YqHC6ESnyb1M/YxcWxpH44UcVHc7Qk6GgEGT2TGMLycbe { "type" : "error", "id" : "17a47682-8d47-4655-a414-a58bdbcd46f9", "code" : "forbidden", "description" : "You don't have the rights to send bank card details: you need a PCI DSS certificate and a permission on YooMoney's side. Contact your YooMoney manager to learn more" }
Примеры ситуаций, когда может возвращаться эта ошибка:
- вы пытаетесь использовать функциональность, которую нужно предварительно согласовывать с менеджером ЮKassa (например, использование автоплатежей в реальном, а не тестовом магазине);
- для OAuth: вы пытаетесь выполнить операцию, для которой не запрашивали права, например если вы изначально выбрали недостаточно прав или сначала получили токен, а затем отредактировали настройки приложения.
Причина возникновения ошибки указана в теле ответа, в параметре
description
. При необходимости тело ответа содержит parameter
с названием параметра, из-за которого возникла ошибка.Поправьте ошибки и повторите запрос с новым ключом идемпотентности.
Если запрос корректный, но вы запрашиваете ресурс, которого не существует, API вернет HTTP 404. В теле ответа будет указана возникшая ошибка. Описание параметров тела ответа
Пример ответа
HTTP/2 404 Server: nginx Date: Thu, 21 Apr 2022 08:09:24 GMT Content-Type: application/json;charset=UTF-8 Content-Length: 254 Signature: v1 29f324f4 1 MGQCMD6EOqWtagcxQ7MkfNGOp2FJ22Gqx1dUGWNJB61lplkAHEkIBy1w7AAFiIBl+wzjJgIwL6ZO07qfziF6wHrGH29nFd1fp4m5L1pO+NXkd8HT8n9TdtPhKn8rfsePd2fLhgvG { "type" : "error", "id" : "cadc8c9c-26bb-417d-829d-261010fac3d5", "code" : "not_found", "description" : "Incorrect payment_id. Payment doesn't exist or access denied. Specify the payment ID created in your store.", "parameter" : "payment_id" }
Примеры ситуаций, когда может возвращаться эта ошибка:
- вы запрашиваете объект, который создан в одном вашем магазине, а данные для аутентификации используете для другого вашего магазина;
- вы запрашиваете информацию об объекте GET-методом, но в идентификаторе опечатка.
Причина возникновения ошибки указана в теле ответа, в параметре
description
. При необходимости тело ответа содержит parameter
с названием параметра, из-за которого возникла ошибка.Поправьте ошибки и повторите запрос с новым ключом идемпотентности.
Если вы используете некорректный HTTP-метод, API вернет HTTP 405.
Пример ответа
HTTP/2 405 Server: nginx Date: Thu, 21 Apr 2022 08:14:15 GMT Content-Length: 0 Allow: POST Reason-Phrase: Request method 'GET' not supported Signature: v1 29f32617 1 MGQCMA1qpDjDJjRnA7U+2atTebD+czDZLDE10+tD9CPBDIfNlhjJv3oNyDXuBidZRmN+JgIwB7MPYEpQIFebcpJTLMWaRYGqACgKHXCw+jXTsfqciKCvbqDcYdQ5w4XS7mftKGxT
Поправьте HTTP-метод или эндпоинт в зависимости от того, какую операцию вы собираетесь выполнить (подробнее в Справочнике API). Повторите запрос с новым ключом идемпотентности.
Если в запросе указан некорректный тип контента, API вернет HTTP 415.
Пример ответа
HTTP/2 415 Server: nginx Date: Tue, 12 Apr 2022 15:48:10 GMT Content-Length: 0 Accept: application/json Reason-Phrase: Content type 'text/html;charset=utf-8' not supported Signature: v1 29e7b2fa 1 MGQCMDzQ4/8Z/dPinpHZ53DNekEWgbzrFLvCE5dcseoqbnJhMzUauj0zlUliKJMETcpYMAIwTWHFd49yO7AKyyeNnhUNIFcBBpu4Td875W+h8ndI7kJOutnPC3WJBkTOEvfXpApX
Если передаете тело запроса, данные должны быть в формате JSON. Повторите запрос с новым ключом идемпотентности.
Если от вас будет слишком много запросов в течение короткого промежутка времени, API вернет HTTP 429. В теле ответа будет указана возникшая ошибка. Описание параметров тела ответа
Увеличьте интервалы между запросами, чтобы снизить общее количество обращений за единицу времени.
Пример ответа
HTTP/2 429 Server: nginx Date: Wed, 20 Apr 2022 14:04:13 GMT Content-Type: application/json Content-Length: 199 Signature: v1 29f2269d 1 MGUCMQCJiMvqupFLDI4PY0dLlmVK6WnqagBVCk7OFP0qScRAALdPcFXaZZsmgzf6MSgasjICMAQZGgYdZolt98rlGJfdA/m2J7DqSuzddc1NLrzZv71eLiTYBAI+PHZ6EfyNKISGKA== { "type" : "error", "id" : "2a9ab90e-f69f-4844-980b-4e3ec4ff1c86", "code" : "too_many_requests", "description" : "Wow, so many requests! Try to use an exponential backoff of your requests." }
Если ЮKassa по каким-то причинам не может дать точный ответ на запрос, API вернет HTTP 500. В теле ответа будет указано стандартное описание ошибки без детализации причины. Описание параметров тела ответа
Пример ответа
HTTP/2 500 Server: nginx Date: Wed, 20 Apr 2022 14:06:10 GMT Content-Type: application/json;charset=UTF-8 Content-Length: 150 Signature: v1 29f22712 1 MGQCMDPcoCj6+TevC0oZqw0S2qnAqq7gOvLSykARc9G1y6qn6YLsmp095OfrAP3qmSgcmgIwMT5A3a/Wnts0tDn7iVQmBZeqMPeg/brYyPIoli/d5myF9VEaP1hvsaAhJRjVPUnW { "type" : "error", "id" : "dd6112e5-9bc8-4382-9f6d-11e9ec39c9c3", "code" : "internal_server_error", "description" : "Internal server error" }
Чтобы узнать окончательный результат, повторите запрос с теми же данными и с тем же ключом идемпотентности или запросите информацию об объекте методом GET. Если ЮKassa снова вернет HTTP 500, повторяйте запрос с возрастающим разумным интервалом (например, можно использовать последовательность Фибоначчи).
Если прошло более получаса, но вы всё еще получаете HTTP 500, обратитесь в техническую поддержку для выяснения окончательного результата выполнения операции.
Неуспешные платежиТестирование платежейВходящие уведомления