Обработка ответов: коды ответа HTTP — Прием платежей по API ЮKassa

Коды ответа HTTP

Коды ответа (состояния) HTTP, которые может возвращать ЮKassa.

Код ответа HTTP	Код ошибки	Описание
200	—	Запрос успешно обработан. Для POST и GET-запросов ответ содержит созданный, измененный или запрашиваемый объект в актуальном статусе. Для DELETE-запросов тело объекта пустое. Подробнее об обработке HTTP 200
400	invalid_request	Неправильный запрос, нарушен синтаксис или логика запроса. Чаще всего этот статус выдается из-за нарушения правил взаимодействия по API. Подробнее об обработке HTTP 400
401	invalid_credentials	Некорректные данные для аутентификации запроса (идентификатор и секретный ключ, OAuth-токен). Подробнее об обработке HTTP 401
403	forbidden	Не хватает прав для совершения операции. Подробнее об обработке HTTP 403
404	not_found	Запрашиваемый ресурс не найден. Подробнее об обработке HTTP 404
405	—	Некорректный HTTP-метод запроса. Например, ошибка возникает при попытке отправить запрос на отмену платежа методом GET вместо POST. Подробнее об обработке HTTP 405
415	—	Некорректный тип контента для POST-запроса. Подробнее об обработке HTTP 415
429	too_many_requests	Превышен лимит запросов в единицу времени. Подробнее об обработке HTTP 429
500	internal_server_error	Технические неполадки на стороне ЮKassa. Результат обработки запроса неизвестен. Подробнее об обработке HTTP 500

HTTP 200

Если запрос обработан успешно, API вернет HTTP 200 и тело ответа с результатом выполнения запроса. Формат тела ответа зависит от запроса (подробнее в Справочнике API).

Пример ответа

HTTP
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, обратитесь в техническую поддержку.

HTTP 400

Если запрос некорректный с точки зрения синтаксиса или логики API ЮKassa, API вернет HTTP 400. В теле ответа будет указана возникшая ошибка. Описание параметров тела ответа

Пример ответа

HTTP
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 с названием параметра, из-за которого возникла ошибка.

Поправьте ошибки и повторите запрос с новым ключом идемпотентности.

Эти ошибки необходимо поправить в процессе интеграции, чтобы при проведении реальных операций все запросы были корректными и ЮKassa могла их обработать.

HTTP 401

Если в заголовке запроса отсутствует параметр Authorization или с переданными данными для аутентификации что-то не так, API вернет HTTP 401. В теле ответа будет указана возникшая ошибка. Описание параметров тела ответа

Пример ответа

HTTP
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 Basic Auth

Примеры ситуаций, в которых может возвращаться код ответа HTTP 401 при использовании HTTP Basic Auth:

в запросе нет идентификатора или секретного ключа;
идентификатор и секретный ключ указаны в неправильном порядке или формате;
идентификатор не соответствует тому магазину, в который вы хотите провести операцию, или в идентификаторе опечатки;
указанный секретный ключ неактуальный или содержит опечатки.

Причина возникновения ошибки указана в теле ответа, в параметре description. Поправьте ошибки и повторите запрос. Ключ идемпотентности можно использовать тот же или сгенерировать новый.

OAuth

Только для тех, кто использует API для партнеров.

Примеры ситуаций, в которых может возвращаться код ответа HTTP 401 при использовании OAuth-авторизации:

вы не передали OAuth-токен;
в токене есть опечатки;
вы удалили приложение, для которого был выдан этот токен;
токен устарел;
пользователь отозвал токен.

Причина возникновения ошибки указана в теле ответа, в параметре description. Поправьте ошибки, при необходимости получите токен заново и повторите запрос. Ключ идемпотентности можно использовать тот же или сгенерировать новый.

HTTP 403

Если запрос корректный, но не хватает прав для совершения операции, API вернет HTTP 403. В теле ответа будет указана возникшая ошибка. Описание параметров тела ответа

Пример ответа

HTTP
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: вы пытаетесь выполнить операцию, для которой не запрашивали права, например если вы изначально выбрали недостаточно прав или сначала получили токен, а затем отредактировали настройки приложения.

Поправьте ошибки и повторите запрос с новым ключом идемпотентности.

HTTP 404

Если запрос корректный, но вы запрашиваете ресурс, которого не существует, API вернет HTTP 404. В теле ответа будет указана возникшая ошибка. Описание параметров тела ответа

Пример ответа

HTTP
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-методом, но в идентификаторе опечатка.

Поправьте ошибки и повторите запрос с новым ключом идемпотентности.

HTTP 405

Если вы используете некорректный HTTP-метод, API вернет HTTP 405.

Пример ответа

HTTP
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). Повторите запрос с новым ключом идемпотентности.

HTTP 415

Если в запросе указан некорректный тип контента, API вернет HTTP 415.

Пример ответа

HTTP
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. Повторите запрос с новым ключом идемпотентности.

HTTP 429

Если от вас будет слишком много запросов в течение короткого промежутка времени, API вернет HTTP 429. В теле ответа будет указана возникшая ошибка. Описание параметров тела ответа

Увеличьте интервалы между запросами, чтобы снизить общее количество обращений за единицу времени.

Пример ответа

HTTP
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."
}

HTTP 500

Если ЮKassa по каким-то причинам не может дать точный ответ на запрос, API вернет HTTP 500. В теле ответа будет указано стандартное описание ошибки без детализации причины. Описание параметров тела ответа

Пример ответа

HTTP
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"
}

HTTP 500 не говорит об успешности или неуспешности выполнения операции. Например, могут быть ситуации, когда платеж успешно прошел, но ЮKassa по каким-то причинам не смогла сообщить вам результат.

Чтобы узнать окончательный результат, повторите запрос с теми же данными и с тем же ключом идемпотентности или запросите информацию об объекте методом GET. Если ЮKassa снова вернет HTTP 500, повторяйте запрос с возрастающим разумным интервалом (например, можно использовать последовательность Фибоначчи).

Если прошло более получаса, но вы всё еще получаете HTTP 500, обратитесь в техническую поддержку для выяснения окончательного результата выполнения операции.

Что почитать еще

Неуспешные платежи Тестирование платежей Входящие уведомления