BAAS API errors

This section describes the errors of methods on the domains:

• Production — api.baas.kvell.group
• Stage — api.baas.stage.kvell.group

Response format

The BAAS API returns errors in the errors array. For a validation error, a field field is also returned.

Validation errorOther error

Validation error example

{
  "errors": [
    {
      "code": 0,
      "message": "Input should be less than or equal to 100",
      "field": "size"
    }
  ]
}

Authorization error example

{
  "errors": [
    {
      "code": 11,
      "message": "Invalid signature"
    }
  ]
}

Response parameters

Parameter	Type	Description
errors	array	List of errors. Multiple validation errors can be returned for a single request.
∟ code	integer	BAAS API error code.
∟ message	string	Error description.
∟ field	string	The field with an invalid value. Returned only for validation errors.

List of errors

Codes with a fixed HTTP status are grouped by status and do not repeat between tables. Codes 0 and 4 are described separately, since their HTTP status depends on the cause of the error.

HTTP 400 — bad request

Code	Message	What it means and what to do
2	Invalid JSON	Check the JSON syntax, value types, and the Content-Type header, then retry the request.
3	Invalid data	Check the parameters against the method documentation and retry the request after fixing them.
32	The receipt cannot be canceled	Check the receipt's status. Only a receipt in a status that allows cancellation can be canceled.
35	The receipt cannot be canceled yet, try again later	The receipt is in the await_confirm status; its identifier in the revenue registration system has not yet been received. Retry the request later.
41	Card issuance profile not found	Contact your KVELL manager to configure the card issuance profile.
51	The order amount does not match the act amount	Check the order amount and the total amount of the act's line items, then retry the request after fixing it.

HTTP 401 — authorization error

Code	Message	What it means and what to do
10	Invalid api-key	Check the API key and the request environment.
11	Invalid signature	Check the signature algorithm for the called method, the order of values, secret_key, and the data being signed.

HTTP 403 — access denied

Code	Message	What it means and what to do
12	Access denied	Make sure the shop is active and allowed to access the BAAS API.
42	Access denied	The shop does not have access to the requested service. Check the service connection with your KVELL manager.

HTTP 404 — data not found

Code	Message	What it means and what to do
20	Shop not found	Check X-Api-Key and the selected environment: Production or Stage.
21	Merchant not found	Check the merchant identifier and shop settings.
30	Receipt not found	Check the receipt identifier and the shop on whose behalf the request is made.
31	Client not found	Check the client identifier and the shop on whose behalf the request is made.
40	Application not found	Check the card issuance application identifier.
43	Profile for Sber not found	Contact your KVELL manager to configure the Sber profile.
44	User not found	Check the user identifier and the shop on whose behalf the request is made.
50	Order not found	Check the order identifier and the shop on whose behalf the request is made.

HTTP 422 — validation error

Code	Message	What it means and what to do
5	At least one field must be filled in	Pass at least one of the parameters listed in the method documentation.
6	One of the fields must be passed: transactions or orders	Pass exactly one field: transactions or orders. Do not pass both at the same time.

Format errors for individual fields are also returned with HTTP 422, but use code 0, described in the section «Codes with a variable HTTP status».

HTTP 500 — internal error

Code	Message	What it means and what to do
1	Unknown error	An unhandled technical error occurred. Use the recommendations from the section «Technical errors and no response».

HTTP 503 — service unavailable

Code	Message	What it means and what to do
45	SMEV unavailable	The SMEV service is temporarily unavailable. Retry the request later; if the error persists, contact support.

Codes with a variable HTTP status

Code	HTTP status	Message	What it means and what to do
0	Depends on the error	Determined by the cause of the error	For a validation error, fix the parameter from field. If field is absent, check the URL, HTTP method, and response message.
4	Status of the dependent service	Depends on the service's response	The dependent service returned an error. Handling is described in the section «Dependent service error».

Validation errors

For format errors in headers, query parameters, path parameters, and the request body, the BAAS API returns HTTP 422 and code 0. The field field contains the name of the invalid parameter, and message contains the reason for the error.

A single response can contain multiple errors elements. Fix all the listed fields before retrying the request.

Example of multiple validation errors

{
  "errors": [
    {
      "code": 0,
      "message": "Field required",
      "field": "x-api-key"
    },
    {
      "code": 0,
      "message": "Field required",
      "field": "x-signature"
    }
  ]
}

Dependent service error

Code 4 means that a dependent service returned an error. The BAAS API preserves its HTTP status, and passes the extracted description of the cause in message. Because of this, code 4 can occur in both 4XX and 5XX responses.

The handling order depends on the HTTP status:

1. For 4XX, check the request parameters and the description in message. Do not retry the request without fixing the cause.
2. For 5XX, use the technical error handling rules for the called method.
3. If the cause is unclear or the error persists, contact support and provide X-Request-ID, the HTTP status, code, and message.

Technical errors and no response

The course of action depends on the type of method:

• for a read-only method, safely retry the request with the same parameters; if the signature includes X-Request-ID, generate a new identifier and recalculate the signature;
• for a method that creates or modifies data, do not perform an automatic retry until you have checked the recommendations on the method's page and determined the result of the original request;
• if no response is received due to a timeout or a dropped connection, the client will not have a body with errors.

For recurring technical errors, contact support and provide the method's URL, the request time, X-Request-ID, and the response received, if any.