Error codes

This document lists every error.code that the public routes under /v1 and /checkout/v1 return, with the HTTP status the service uses and what the client should do. Read it when writing the error handling of an integration.

Error body

Every error response of the API has the same body:

{ "error": { "code": "route_not_found", "message": "Route not found" } }

Every response, including errors, has the X-Request-Id header. Give its value to the operator when you report a problem: it finds the request in the logs. If the client sends its own X-Request-Id of 1–128 Latin letters, digits and the characters ., _, :, -, the service uses it; otherwise the service generates a UUID.

The OpenAPI description, GET /v1/openapi.json, declares one list of codes for all routes of the service, internal ones included. A public route returns only the codes from the list below.

Two kinds of responses do not have this body:

• the HTTPS proxy answers a path outside /v1/ with 404 and an empty body;
• while the API is shutting down, it answers 503 with a body in a different format.

Handle a response whose body is not in the format above by its HTTP status.

How to handle errors

• 400, 413, 415 — the request is wrong. Fix it: the same request gets the same error.
• 401 — check the key and the header name.
• 403 — the merchant is disabled or not approved. Requests keep failing until the owner or the operator changes that.
• 404 — check the path and the identifier.
• 409 — the request conflicts with an existing object: an idempotency key (order_id, reference) is reused with different data, or a token choice on the checkout page is already made or no longer possible. Do not retry the same request.
• 422 — the request is well-formed, but a business rule refuses it; the code names the rule. The same request gets the same error until the setting behind the rule changes.
• 429 — retry after the number of seconds in the retry-after header.
• 500, 503 — a problem of the service. Retry later with a growing delay and the same idempotency key: order_id for an invoice, reference for a payout. A retry does not create a second object.
• A code that is not in the list — handle the response by its HTTP status class: 4xx is an error in the request, 5xx is a problem of the service.

Code list

Examples

A path that does not exist:

curl -s https://api.stons.io/v1/unknown

404:

{"error":{"code":"route_not_found","message":"Route not found"}}

A request to POST /v1/invoices with "expires_in": 60 fails schema validation, and details lists every problem field:

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed",
    "details": [{ "path": "body.expires_in", "message": "Too small: expected number to be >=300" }]
  }
}

A request with "asset": "USDT_TRON" and "amount": "49.9000001" passes schema validation and fails the check of decimals, so there is no details:

{
  "error": {
    "code": "validation_failed",
    "message": "amount: amount has more than 6 digits after the decimal point (USDT_TRON has 6 decimals)"
  }
}