YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
HTTP response codes
HTTP response (status) codes that YooMoney can send in response to a request.
HTTP response codeError codeDescription
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.
401
invalid_credentials
Incorrect data for request authentication (identifier and secret key, OAuth token).
403
forbidden
Not enough rights to perform the operation.
404
not_found
Requested resource is not found.
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.
415
Incorrect type of content for a POST request.
429
too_many_requests
The limit of requests per unit of time has been exceeded.
500
internal_server_error
Technical difficulties on the YooMoney’s side. Processing results unavailable.
 
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.
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
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
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.
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.
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.
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.
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"
}
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.
See also