HTTP response errors

KVELL returns API errors in a single JSON format. One HTTP status can correspond to several codes, so when processing the response, check the errors[].code value.

Response format

Example error response

{
  "errors": [
    {
      "code": 20098,
      "message": "amount: Field required"
    }
  ]
}

Response parameters

Parameter	Type	Description
errors	array	List of errors.
errors[].code	integer	Error code.
errors[].message	string	Error description.

List of errors

What this reference covers

Below are the standard errors. Bank reasons for declining a transaction are passed in the error_code field and are described separately in the «Transaction error codes» section.

HTTP 400 — request execution error

Code	Message	What it means and what to do
20001	Invalid api-key	Check the key value and the request environment.
20002	Invalid signature	Sign the exact body of the request being sent and retry the request.
20003	Payment/Payout profile is not linked to the shop	Contact your KVELL manager to configure the required profile.
20004	Session not found	The session is missing or has expired. Start a new operation flow.
20005	Error from the PSP service	The payment service or bank returned a processing error after the operation was created.
20007	Transaction already performed	An operation with this transaction already exists. Request its status, do not create a duplicate.
20008	Unhandled status for processing the payment	A status was received that cannot be handled in the current flow. Request the operation's current status.
20010	Invalid email format	Fix the email and retry the request.
20011	Invalid invoice expiration date	Fix the invoice expiration date and retry the request.
20012	Order not completed	Wait for the order's final status before the next operation.
20013	Order is not a payment	Check the type of the source operation.
20014	Error sending email	Check the recipient's address and retry sending later.
20015	Insufficient funds	The operation with the source transaction was canceled. Top up the balance and create a new attempt with a new transaction.
20016	Account not found	Check the account settings or contact support.
20018	You must choose a single method for storing the card on the bank's side	Leave only one card-saving method in the request.
20019	Shop payout limit exceeded	Reduce the amount or change the limit, then retry the request.
20022	Failed to get terminal settings to verify the T-Bank token	Check the terminal settings or contact support.
20023	Cannot refund funds for an incomplete operation	Wait for the source operation to complete.
20024	Refund error	Check the status of the source operation and the refund before retrying.
20025	Refund amount exceeds the order amount	Reduce the refund amount.
20026	Cannot cancel an incomplete operation	Wait for the source operation to complete.
20027	Preauthorization cancellation error	Check the operation status and contact support if the error recurs.
20028	Cannot confirm an incomplete operation	Wait for a status that allows confirmation.
20029	Preauthorization confirmation error	Check the operation status and contact support if the error recurs.
20030	Confirmation amount exceeds the order amount	Reduce the confirmation amount.
20039	Sber profile is not linked to the shop	Contact your KVELL manager to configure the Sber profile.

HTTP 401 — authorization error

Code	Message	What it means and what to do
20032	Invalid key	Check the access key and retry the request.

HTTP 403 — access denied

Code	Message	What it means and what to do
20037	Access denied	Make sure the shop is active and allowed to access the API.
20038	Invalid draft number	The shop does not have access to the specified payout draft.

HTTP 404 — data not found

Code	Message	What it means and what to do
20006	Shop not found	Check X-Api-Key and the request environment.
20009	Order not found	Check the transaction and the shop on whose behalf the request is made.
20031	No data found for the key in the cache	The data is missing or has expired. Repeat the original flow that creates it.
20033	Task for obtaining the certificate not found	Check the task identifier.
20036	Contract not found	Check the contract identifier.
20040	Payout draft not found	Check the draft identifier and the shop.

HTTP 422 — validation error

Code	Message	What it means and what to do
20017	customer_key is not set	Pass customer_key in the flow where it is required.
20020	Recipient is not set	Pass the recipient's data.
20021	At least one field must be filled in	Pass at least one field to change.
20041	The resulting description field exceeds the allowed length	Shorten description, generate a new signature, and retry the request.
20042	Data from the payout and the payout draft do not match	Bring the request data in line with the draft.
20098	Field validation error	Fix the field named at the start of message, generate a new signature, and retry the request.

HTTP 5XX — internal error

Code	Message	What it means and what to do
20000	Unknown error	The operation's result is unknown. Use the technical error handling algorithm below.
20043	The cryptogram public key is temporarily unavailable	HTTP 503. The key was not issued. Safely retry the public key request.

Codes with a variable HTTP status

Code	HTTP status	Message	What it means and what to do
20099	Status of the dependent service	Depends on the service's response	The dependent service returned an error. Handling is described in the «Dependent service error» section.

Dependent service error

Code 20099 means the dependent service returned an error. KVELL preserves its HTTP status, and passes the extracted reason description in errors[].message. So code 20099 can occur in both 4XX and 5XX responses.

Handling depends on the HTTP status:

1. For 4XX, check the request parameters and the description in errors[].message. Do not retry the request without fixing the cause.
2. For 5XX, use the technical error handling rules on the page of the API method being called.
3. If the cause is unclear or the error recurs, contact support and provide the API method URL, the request time, the HTTP status, errors[].code, and errors[].message.

Technical errors and no response

A 5xx response, a timeout, or a connection drop means the operation's result is unknown: the request may have been processed even if the client did not receive a response.

1. Leave the operation in your system in a "processing" state.
2. Request its status using the source transaction.
3. Do not create a repeat operation with a new transaction until the result of the source operation is established.
4. If status requests keep failing, contact support and provide the transaction.