Handling Errors

Clients integrating against the Safepay Nordic 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 cancelling.

Not every request is safe to retry. Read requests (GET) can always be retried. For requests that create something or move money, send an Idempotency-Key header so a retry can't perform the action twice.

Idempotency

These endpoints accept an Idempotency-Key header:

• POST /v2/transactions/marketplace
• POST /v2/transactions/auto
• POST /v2/transactions/{transactionId}/payout
• POST /v2/transactions/{transactionId}/cancel
• POST /v2/payments

Generate a unique key, for example a UUID, for each action, and send the same key when you retry that action. The key can be at most 200 characters.

-H "Idempotency-Key: 81784a78-8b7f-4e49-ad4e-383417c970cf"

• The first request with a key is processed as normal, and its response is stored.
• Retrying with the same key and the same request returns the stored response, with an Idempotency-Replayed: true header. The action isn't performed again.
• 409 Conflict: a request with the same key is still being processed. Wait and retry.
• 422 Unprocessable Entity: the key was already used for a different request. Use a new key for a new action.

Responses with a 5XX status aren't stored, so a request that failed with a server error is processed again when retried with the same key.

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 a client error occurs, most endpoints return a problem details object describing the issue. Here's an example:

API error example

{
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "Invalid amount",
    "status": 400,
    "detail": "The 'amount' field is too low. The sum of costs is not covered in the amount"
}

title and detail describe what went wrong. The error titles for each endpoint are listed on the flow pages.

Some responses, typically 404 Not Found, have no body. Rely on the HTTP status code, and only read the body when there is one.

If you need help from our support team, include the time of the request and, if you sent one, the X-Correlation-Id header.

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.

Unauthorized (401)

The API key is missing or invalid. Check the Authorization header, and generate a new key in the portal if needed. See API key.

Not Found (404)

The requested entity could not be found, or it doesn't belong to you.

Conflict (409)

A request with the same Idempotency-Key is still being processed. See Idempotency.

Unprocessable Entity (422)

The Idempotency-Key was already used for a different request. See Idempotency.