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