Error Handling

This guide is intended for all Wise Platform partners to understand how Wise API error codes function and how best to build your integration around them.

Wise error responses generally fall into two categories, system errors and client errors. Your integration should be built to accommodate both of these situations, typically by either passing the Wise error message through to your UI or mapping the Wise error to your own application messages. All Wise error responses can be structured as a simple response with relevant fields, or an array containing one or more objects related to the error flow.

While we are actively working to improve our API error codes, at this time Wise error codes are not unique, and are used in conjunction with a provided payload body to determine the specific error.

System Errors

System errors are not typically caused by the end user, and often require your involvement to remedy the cause of the error. Generally these errors should be handled by mapping the error or path field to a friendly UI response, though some of these errors may have end user messages or relevant fields to pass through.

System Error Example

{
  "error": "invalid_token",
  "error_description": "945fdc16-56cb-4039-90b4-998d583740ce"
}

Client Errors

Client errors consist of issues solvable by the end user, or application client issues that you should design your application around. These errors include causes such as missing data input, poorly formatted inputs, or your application not enforcing required fields for the end user.

Example of end user issue

{
  "errors": [
    {
      "code": "error.greaterThanZero",
      "message": "Please type in a number that's larger than 0.",
      "path": "sourceAmount",
      "arguments": []
    }
  ]
}

Example of application error to build for

{
  "errors": [
    {
      "code": "ERROR",
      "message": "Unable to parse number [null]",
      "path": "targetRecipientId",
      "arguments": [
        "targetRecipientId"
      ]
    }
  ]
}

HTTP Status Codes

We use common HTTP status codes included in the response header to indicate success or failure.

Error Codes

Code	Description
200	OK. Successful request.
201	OK. Resource created.
400	Bad request. Request message data did not pass validation.
401	Unauthorised. Not authorised to access requested data.
403	Forbidden. Access to requested data is forbidden.
404	Not Found. Requested resource does not exist.
408	Timeout. Operation timed out.
422	Unprocessable entity. Request message data did not pass validation.
429	Too Many Requests
500	Server error.

Too Many Requests

An HTTP 429 response status code indicates that the client has sent too many requests in a given time frame. The default thresholds are:

100 requests per second
1000 requests per minute

Handling 429 responses:

Implementing a retry mechanism with exponential backoff. For some of the responses we will include a header: Retry-After in seconds, which indicates the minimum time after which the request should be retried
Reducing the rate of requests (for example if executing batch requests - limit the number of concurrent http requests)
Contact Wise with a request to increase request thresholds

Too Many Requests Example

HTTP/1.1 429 Too Many Requests
Content-Length: 0
Content-Type: application/json
Retry-After: 60