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"
}

Where

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.).

HTTP status	Code	Details.Code	Message
401	11001		UserId was not found in provided authentication data
400	12001		There were OData validation errors
400	12002		Input binding failed
400	21000		One or more preconditions failed
400	21000	1001	Asset with uinque Id '{uniqueAssetId}' does not exist
400	21000	1002	the user '{userId}' does not own asset ('uniqueAssetId') issuer's address '{assetIssuerAddress}'
400	21000	1003	invalid units amount provided (must be positive integer): '{providedAmount}'
400	21000	1004	spark factor is not defined for the asset '{uniqueAssetId}'
400	21000	1005	the user '{userId}' does not own signer address '{signerAddress}'
400	21000	1006	not enough sparks on the balance. Address: {signerAddress}, uniqueAssetId: {uniqueAssetId}, required amount: {requiredAmount}, actual amount: {actualAmount}
400	21000	1007	the instance is configured to operate on assets from ledger {configuredLedgerId}, but the requested asset '{uniqueAssetId}' is from ledger {assetLedgerId}
400	21000	1008	The source asset with Id '{sourceUniqueAssetId}' is already linked to asset with id '{targetUniqueAssetId}'
400	21000	1009	The source asset with Id '{sourceUniqueAssetId}' is not linked to asset with id '{targetUniqueAssetId}'
400	22000		One or more validations failed
400	22000	2001	Either asset name or issuer address should be provided in search request
400	22000	2002	Issuer address value should be 40 or 42 symbol long
400	22000	2003	Valid language code should be provided for asset
400	22000	2004	Valid jurisdiction should be provided for asset
400	22000	2005	Asset's unit of measure is not valid
400	22000	2006	Asset's spark factor is not valid
400	22000	2007	Asset's asset class is not valid
400	22000	2008	The number of sections in asset custom definition item's SectionsPathNames differs from SectionsPath
400	22000	2009	Offered asset unqueId must be specified in request
400	22000	2010	Desired asset unqueId must be specified in request
400	22000	2011	Desired and offered assets unqueIds must differ
400	22000	2012	Either offered or desired amount of sparks must be specified in request but not both
400	22000	2013	Signer address must be specified
400	22000	2014	Input amount must be a positive integer
400	22000	2015	Array of supply ids must contain at least one supply id
400	22000	2016	Array of target unique asset ids must not be empty

400	22000	2017	User can delete only his own data
400	23000		`<Sdk error code>:<Sdk error message>`

Error Responses​

Error Responses