Handling errors

Error response structure, errors overview

Requests made to our APIs can result in several different error responses. The following document describes a list of error values with a map to the most common recovery tactic to use.

Error Responses

TEOS API is using HTTP status codes as a highest level of response codes. Following status codes can be returned by TEOS API:

  • HTTP 4xx - error on the client side

    • HTTP 400 - request body error(incorrect parameters, failed preconditions)

    • HTTP 401/403 - error with authentication/authorization

    • HTTP 404 - error in resource URI

  • HTTP 500 - internal server error

The following json-structure represents a common error response body resulting from a failed API request:

  "code": "21000",
  "message": "One or more preconditions failed",
  "target": "assets('090299f8f5d95aea86f280001')/destroyunits",
  "details": [
      "code": "1006",
      "message": "not enough sparks on the balance. Address: 0xe0450ce1e2ef73b15514ae6a003b90d0ebac8835, required amount: 50, actual amount: 0",
      "arguments": {
        "signerAddress": "0xe0450ce1e2ef73b15514ae6a003b90d0ebac8835",
        "requiredAmount": "50",
        "actualAmount": "0"
  "clTraceId": "12a56f61-54f8-44fd-9f74-d0d2bbd942f6"


  • code: high-level error code

  • message: a message, describing the issue

  • target: the path requested

  • details: depending on the error, may be present or not. They specify the details of the error.

    • code: the subcode of the issue

    • message: a message, describing the details of the issue

    • arguments: if a message contains any data (strings, decimals etc), that need to be used for i18n of the error message, this field contains the names and the values of the data

  • clTraceId: Internal support identifier. When reporting a bug related to a TEOS API call, include the clTraceId to help us find log data for debugging.

Error codes 1xxxx indicate non-business logic related issues with input (auth issues, issues with parsing input data, rate limiting etc.). These errors are mostly 'technical', related to the problems in the TEOS API consumer's code.

Error codes 2xxxx indicate business logic related issues with input (failed preconditions, validations etc.).

Last updated