Errors
What an API error looks like, how to handle it and which errors are possible today.
An error returned by the application always has the same shape, on any endpoint and with any HTTP status.
{
"error": {
"code": "unknown_filter",
"message": "Unknown parameters: verbose",
"details": {
"unknown": [
"verbose"
],
"allowed": []
}
}
}| Field | Type | Present | Description |
|---|---|---|---|
error | object | always | The error itself. A successful response never has this field. |
error.code | stringunauthorized cookie_auth_not_allowed forbidden unknown_filter bad_body too_large not_found too_many_requests not_implemented internal validation_failed bad_amount conflict identifier_invalid keyring_unavailable dependency_unavailable | always | Error code. The client decides what to do by it. Common codes are listed in the catalogue below, the codes of a single endpoint in the reference under it. |
error.message | string | always | Explanation for a person, in English. The text may change: do not parse it in code. |
error.details | any value | not always | Details, if any. Their content depends on the code; often it holds rule, and a validation error also holds field. |
How to handle an error
- The HTTP status says whose fault it is. A 4xx status: the request must be fixed, retrying it unchanged gives the same response. The exceptions are retried later with the same request: 429, 409 with the rule
request_in_progressorrefund_in_progress, 409 without a rule andkeyring_unavailablewhen creating a payment. A 5xx status: a failure on our side. error.codesays what exactly is wrong.error.details.rule, if present, names the exact reason. Authentication errors differ by it.
Handle an unknown code by its HTTP status: new codes and rules may appear, and the changelog announces them.
The text in error.message is written for a person, in English, and may change. Do not parse it in code: branch on error.code and error.details.rule.
If the application is down entirely, a 502 or 504 response comes from the proxy in front of it, and such a response has no body in this shape. Do not parse it as JSON; treat it like any other 5xx.
Request ID
Every response, successful or not, has an X-Request-Id header. Save it together with the error in your log and quote it to support: it lets us find the request at once.
Error catalogue
These errors are common to all endpoints; an endpoint's own errors are described in the reference under it. Under each row you can expand an example response.
Authentication
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 401 | unauthorized | There is no Check that the header is sent and that the key is copied in full, without spaces or line breaks. |
Example response | ||
| 401 | unauthorizedapi_key_revoked | The key is valid but has been revoked or replaced by regeneration. Revocation is final. Get a new key from your administrator. |
Example response | ||
| 401 | unauthorizedapi_key_expired | The key is valid but has expired. Get a new key from your administrator. |
Example response | ||
| 401 | unauthorizedapi_key_disabled | The key is valid but an administrator has disabled it. A disabled key can be enabled again. Ask your administrator to enable the key. |
Example response | ||
| 401 | cookie_auth_not_allowed | The request came with a session cookie of the operator console. This happens when a request is copied from the browser's network panel. Remove the cookie and send the API key in the |
Example response | ||
| 403 | forbiddenmerchant_not_active | The key is valid but the merchant is not active: not yet activated, disabled or archived. Check the merchant's status with your administrator. |
Example response | ||
| 403 | forbiddenenvironment_closed | The key is valid and the merchant is active, but this key's environment is closed for the merchant. Use a key of the other environment or ask your administrator to open this one. |
Example response | ||
Request
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 400 | unknown_filter | The URL has a parameter the endpoint does not have. An unknown parameter is never silently ignored: Remove the parameter or fix its name. |
Example response | ||
| 400 | bad_body | The request body could not be parsed as JSON. Fix the request body. |
Example response | ||
| 413 | too_large | The request body is larger than allowed. Make the request body smaller. |
Example response | ||
| 404 | not_found | No such path: a typo in the path or the wrong HTTP method. Check the path and the method against the reference. |
Example response | ||
Rate limit
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 429 | too_many_requests | The rate limit for requests from one address has been exceeded. Retry later: the |
Example response | ||
Our side
| HTTP | Code and rule | When it happens and what to do |
|---|---|---|
| 500 | internal | A failure on our side. The cause is not disclosed; Retry the same request later, payment and refund creation with the same retry key. If it keeps happening, give support the request ID. |
Example response | ||