Handling Errors

Clients integrating against the Symblepay API should expect intermittent errors and must implement suitable error handling. Errors can generally be classified into three categories: network errors, server errors, and client errors. Network and server errors should be handled by retrying requests, while client errors should be handled by fixing the client request.

Network and Server Errors

Network errors typically present themselves as timeouts or connections that are closed prematurely. Network errors and server errors (HTTP 5XX responses) should initially be handled by retrying requests. If errors persist despite retries, the flow should be cleaned up e.g. by canceling. The Symblepay API uses idempotency to ensure that requests can always be safely retried. Idempotency ensures that performing the same call multiple times will not cause additional state changes beyond those caused by the first call.

Retry policy

We recommend retrying failed requests due to network and server errors using one of these strategies:

• Retrying requests up to a fixed number of times with a constant delay between each call.

• Retrying requests up to a fixed number of times using an exponential backoff with jitter strategy (i.e. doubling the delay between each retried call and adding some randomness to the delay to avoid overloading the backend).

We suggest retrying a failed request 2 times (which results in 3 requests including the first one).

You may retry max 5 times (which results in 6 requests).

Errors

If any client errors occur, our endpoints return an error object describing the issues encountered. Each error object has the same contract. Here's an example:

Marketplace API error example

{
    "type": "https://developer.symblepay.io/docs/guidelines/errors#not-found",
    "title": "Entity not found",
    "status": 404,
    "detail": "The requested entity could not be found.",
    "instance": "v1/marketplace/trade",
    "traceId": "d468dfbe-323d-48a4-8399-e6104876331a",
    "typeCode": "not-found"
}

title and detail are the properties you should be interested to. traceId and instance properties should be provided for our support team in case you need their help with any issues. The values of those properties help to find solutions quicker.

Error Codes

Bad Request (400)

The request could not be understood by the server due to malformed syntax, missing parameters, or other invalid data. Please review your request and ensure all parameters are correctly formatted and provided.

Not Found (404)

The requested entity could not be found.