Response handling: HTTP response codes — Payment acceptance via the YooMoney API

HTTP response codes

HTTP response (status) codes that YooMoney can send in response to a request.

HTTP response code	Error code	Description
200	—	The request was successfully processed. For POST and GET requests, the response contains the created, modified, or requested object in its current status. For DELETE requests, the object body is empty. More about processing HTTP 200
400	invalid_request	Invalid request, error in request syntax or logic. This status is most commonly associated with rule violations regarding the interaction with the API. More about processing HTTP 400
401	invalid_credentials	Incorrect data for request authentication (identifier and secret key, OAuth token). More about processing HTTP 401
403	forbidden	Not enough rights to perform the operation. More about processing HTTP 403
404	not_found	Requested resource is not found. More about processing HTTP 404
405	—	Incorrect HTTP method of the request. For example, the error is returned in response to an attempt to send a payment cancellation request via GET method instead of POST. More about processing HTTP 405
415	—	Incorrect type of content for a POST request. More about processing HTTP 415
429	too_many_requests	The limit of requests per unit of time has been exceeded. More about processing HTTP 429
500	internal_server_error	Technical difficulties on the YooMoney’s side. Processing results unavailable. More about processing HTTP 500

HTTP 200

If the request is processed successfully, the API will return HTTP 200 and a response body with the results of the request. The format of the response body depends on the request (more details in the API Reference ).

Example of a response

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" : "Order No. 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"
  }
}

Some objects, such as payments, have a status. It reflects the results of operation processing. For example, if a payment has been created but the user has not confirmed it yet, the status of the payment object will be pending. If the payment is transferred to the balance of your store, the status of the payment object will be succeeded. If for some reason it was not possible to make the payment, the status will be canceled, and the payment object will include the reasons for cancellation.

If you received an object with the pending status in response to a request, you need to wait until the object switches to its final state. There are two ways to track the status change:

Subscribe to incoming notifications and wait for a notification. More about incoming notifications
Repeat the request with the same data and the same idempotency key, or request information about the object using the GET method. If the status of the object does not change, we recommend repeating the request with an increasing reasonable interval (for example, you can use the Fibonacci sequence).

If the created object should have already switched to another status (for example, the time allotted for the confirmation of a payment by the user has expired), yet it still remains in the pending status, contact technical support.

HTTP 400

If the request is incorrect in terms of syntax or logic of the YooMoney API, the API will return HTTP 400. The error will be specified in the response body. Description of response body parameters

Example of a response

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

Examples of instances where HTTP 400 response code may be returned:

missing required parameters;
error in parameter value (wrong format, invalid value);
the request generation logic is broken (for example, only one of the two parameters must be specified, yet both are specified, or the value in one parameter does not match the value in the other parameter);
something is wrong with the idempotency key.

The reason for the error is specified in the description parameter of the response body. If necessary, the response body will contain the parameter value with the name of the parameter that caused the error.

Correct the errors and repeat the request with a new idempotency key.

These errors must be corrected during the integration process so that during real transactions all requests are correct and YooMoney can process them.

HTTP 401

If there is no Authorization parameter in the request header or something is wrong with the specified authentication data, the API will return HTTP 401. The response body will contain the error that occurred. Description of response body parameters

Example of a response

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

The procedure depends on your method of request authentication:

HTTP Basic Auth (store id and secret key);
OAuth (OAuth token) only applies to those who use the API for partners.

HTTP Basic Auth

Examples of instances where HTTP 401 response code may be returned when using HTTP Basic Auth:

the request does not contain an identifier or secret key;
the identifier and secret key are in the wrong order or format;
identifier does not correspond to the store where you want to perform the operation, or there are typos in the identifier;
the specified secret key is deprecated or contains typos.

The reason for the error is specified in the description parameter of the response body. Correct the errors and repeat the request. You can use the same idempotency key or generate a new one.

OAuth

Only for those who use the API for partners.

Examples of instances where HTTP 401 response code may be returned when using OAuth authorization:

you didn't send an OAuth token;
there are typos in the token;
you deleted the app for which this token was issued;
the token is deprecated;
the user has revoked the token.

The reason for the error is specified in the description parameter of the response body. Correct the errors, obtain a new token, if necessary, and repeat the request. You can use the same idempotency key or generate a new one.

HTTP 403

If the request is valid, but there are not enough rights to perform the operation, the API will return HTTP 403. The response body will contain the error that occurred. Description of response body parameters

Example of a response

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

Examples of instances where this error may be returned:

you are trying to use the functionality that needs to be approved by the YooMoney manager in advance (for example, using autopayments in a real, non-demo store);
for OAuth: you are trying to perform an operation that you did not request rights for, for example, if you initially selected insufficient rights, or edited the app settings after receiving a token.

Correct the errors and repeat the request with a new idempotency key.

HTTP 404

If the request is valid, but you're requesting a resource that doesn't exist, the API will return HTTP 404. The response body will contain the error that occurred. Description of response body parameters

Example of a response

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

Examples of instances where this error may be returned:

you request an object that was created in one of your stores, yet use authentication data for your other store;
you request information about an object using the GET method, but there is a typo in the identifier.

Correct the errors and repeat the request with a new idempotency key.

HTTP 405

If you use an invalid HTTP method, the API will return HTTP 405.

Example of a response

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

Correct the HTTP method or endpoint depending on what operation you are going to perform (more details in the API Reference ). Repeat the request with a new idempotency key.

HTTP 415

If an invalid content type is specified in the request, the API will return HTTP 415.

Example of a response

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

If you specify a request body, the data must be in JSON format. Repeat the request with a new idempotency key.

HTTP 429

If you send too many requests within a short period of time, the API will return HTTP 429. The response body will contain the error that occurred. Description of response body parameters

Increase the intervals between requests to reduce the total number of requests per unit of time.

Example of a response

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

If YooMoney for some reason cannot give an exact response to the request, the API will return HTTP 500. The response body will contain a standard error description without detailing the reason. Description of response body parameters

Example of a response

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 does not mean success or failure of the operation. For example, there may be situations when the payment was successful, but YooMoney for some reason could not provide you with the result.

To find out the final result, repeat the request with the same data and the same idempotency key, or request information about the object using the GET method. If YooMoney returns HTTP 500 again, repeat the request at increasing reasonable intervals (for example, you can use the Fibonacci sequence).

If more than half an hour has passed but you are still getting HTTP 500, contact the technical support to find out the final result of the operation.