Catch and respond to invalid data, transfer limits, and more.
Wise error responses fall into two main categories: system errors and client errors.
Your integration should accommodate both by either passing Wise error messages through to your UI or mapping codes to your own application messages.
All Wise error responses are structured as either a simple response with relevant fields or an array containing one or more objects related to the error flow.
Currently, Wise error codes are not unique and must be used in conjunction with the provided payload body to determine the specific error.
System errors are typically not caused by end users and often require developer intervention.
Handle these errors by mapping the error or path field to a user-friendly UI response.
{
"error": "invalid_token",
"error_description": "945fdc16-56cb-4039-90b4-998d583740ce"
}Client errors consist of issues that can be resolved by the end user or application design improvements.
These include missing data input, poorly formatted inputs, or missing required field validation.
{
"errors": [
{
"code": "error.greaterThanZero",
"message": "Please type in a number that's larger than 0.",
"path": "sourceAmount",
"arguments": []
}
]
}We use standard HTTP status codes in response headers to indicate success or failure:
| Code | Description |
|---|---|
| 200 | OK. Successful request |
| 201 | OK. Resource created |
| 400 | Bad request. Request data failed validation |
| 401 | Unauthorized. Not authorized 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 data failed validation |
| 429 | Too Many Requests |
| 500 | Server error |
An HTTP 429 response indicates too many requests in a given timeframe.
Default thresholds:
- 100 requests per second
- 1000 requests per minute
- Implement retry mechanism with exponential backoff.
- Check for Retry-After header indicating minimum retry time.
- Reduce request rate (limit concurrent requests for batch operations).
- Contact Wise to request increased thresholds, if needed.
Passthrough errors should be passed to users as they contain end-user-friendly messages. These are typically related to UI input or form data that users can resolve.
Make sure to only passthrough end-user friendly messages. The message field is not always suitable for UI exposure.
{
"errors": [
{
"code": "MISSING",
"message": "Please enter your first name",
"path": "firstName",
"arguments": ["firstName"]
},
{
"code": "ERROR",
"message": "Unparseable date: \"1234\"",
"path": "dateOfBirth",
"arguments": ["dateOfBirth"]
}
]
}Build passthrough error handling for these flows:
- Dynamic Forms
- Quotes
- Account Management
Depending on your integration type, other errors may be appropriately structured for passthrough.
Partner mapped errors are responses that should not be passed directly to your end-users in the UI. Instead, they should be used for error logging and mapping to your own UI error messages.
This should typically be done for non-end-user-friendly error responses and errors that occur in flows where the end user is unable to resolve the error themselves.
Make sure you build to accommodate both key/value and array responses.
{
"error": "invalid_token",
"error_description": "945fdc16-56cb-4039-90b4-998d583740ce"
}Mapping Wise error responses or building your system to avoid those errors should be done for the majority of errors if they are not specifically listed in the Passthrough errors section.
| Field | Type | Description |
|---|---|---|
timestamp | string | Timestamp when the error occurred |
code | string | Non-unique error code (error category) |
path | string | Unique error name for mapping |
message | string | User-friendly message for UI display |
arguments | array | Additional error-specific information |
error | string | Unique error name for mapping |
error_description | string | Detailed error description |
status | string | Service-specific status |
Endpoint: /v1/user/signup/registration_code
API reference: Create a user with a registration code
Failure: System error
The email you are trying to use to create an account has already been used. To access this account, you would need to perform an OAuth to that account, meaning you would also need to know the password.
{
"errors": [
{
"code": "NOT_UNIQUE",
"message": "You're already a member. Please login",
"path": "email",
"arguments": ["email", "ma********************@wise.com"]
}
]
}Failure: Client error
Missing required fields. The email and registrationCode fields must be supplied in all calls.
{
"errors": [
{
"code": "NotNull",
"message": "must not be null",
"path": "email",
"arguments": []
},
{
"code": "NotNull",
"message": "must not be null",
"path": "registrationCode",
"arguments": []
}
]
}Failure: Client error
The registration code is too small. Increase its size to fit the restrictions.
{
"errors": [
{
"code": "Size",
"message": "size must be between 32 and 2147483647",
"path": "registrationCode",
"arguments": [
"2147483647",
"32"
]
}
]
}Failure: Client error
Email is poorly formatted. Only send proper emails.
{
"errors": [
{
"code": "ERROR",
"message": "Please provide a valid email",
"path": "email",
"arguments": [
"email",
"ma********************@w"
]
}
]
}Endpoint: /v1/profiles
API reference: Profile
Failure: Client error
The type of profile was incorrect. It must be either personal or business.
{
"errors": [
{
"code": "BAD_REQUEST",
"message": "Could not resolve type id",
"arguments": []
}
]
}Failure: Client error
You must pass a details object.
{
"errors": [
{
"code": "BAD_REQUEST",
"message": "Missing details property",
"arguments": []
}
]
}Failure: Client error
For type personal, you must include 4 fields, and they cannot be blank.
Info "Field Requirements":
firstName(cannot be blank)lastName(cannot be blank)dateOfBirth(YYYY-MM-DD format)phoneNumber(with international prefix)
{
"errors": [
{
"code": "MISSING",
"message": "Please enter your first name",
"path": "firstName",
"arguments": ["firstName"]
},
{
"code": "MISSING",
"message": "Property [lastName] cannot be blank",
"path": "lastName",
"arguments": ["lastName"]
},
{
"code": "ERROR",
"message": "Unparseable date",
"path": "dateOfBirth",
"arguments": ["dateOfBirth"]
},
{
"code": "TOO_SMALL",
"message": "Value provided is too short. Please enter a valid phone number",
"path": "phoneNumber",
"arguments": ["phoneNumber", "+123", "5", "25"]
},
{
"code": "UNEXPECTED",
"message": "Please enter a valid phone number",
"path": "phoneNumber",
"arguments": ["phoneNumber", "+123"]
}
]
}Endpoint: /v2/profiles/business-profile
API reference: Create Business Profile
Failure: Client error
Certain fields are required. Please make sure these are provided. Address must be provided, and include the first line, city, and ISO 3 Country code. For businesses that must have a registration number, it is required. For SOLE_PROPRIETORSHIP, this field is optional.
{
"errors": [
{
"code": "api.businessName.missing",
"message": "Please specify the name of your business",
"path": "businessName",
"arguments": null
},
{
"code": "api.registrationNumber.missing",
"message": "Please specify the registration number of your business ",
"path": "registrationNumber",
"arguments": null
},
{
"code": "api.firstLevelCategory.missing",
"message": "Please select a category",
"path": "firstLevelCategory",
"arguments": null
},
{
"code": "api.address.missing",
"message": "Please specify the address of your business",
"path": "address",
"arguments": null
},
{
"code": "api.companyType.missing",
"message": "Please select a company type",
"path": "companyType",
"arguments": null
}
]
}Failure: Client error
Field validation will be completed on supplied fields that are expected, including those that are optional.
{
"errors": [
{
"code": "api.businessName.missing",
"message": "Please specify the name of your business",
"path": "businessName",
"arguments": null
},
{
"code": "api.businessName.invalid",
"message": "Business name contains invalid characters",
"path": "businessName",
"arguments": null
},
{
"code": "api.businessName.size.too.short",
"message": "Business name must be at least 1 character long",
"path": "businessName",
"arguments": null
},
{
"code": "api.companyType.invalid",
"message": "Invalid company type selected",
"path": "companyType",
"arguments": null
},
{
"code": "api.secondLevelCategory.invalid",
"message": "Invalid category selected",
"path": "secondLevelCategory",
"arguments": null
}
]
}Endpoint: /v1/addresses
API reference: Addresses
Failure: Client error
If no body or a profileID that is not owned by the user is sent (including blank and null), you will be given a 403. Ensure that a profileID is provided.
{
"timestamp": "YYYY-MM-DDThh:mm:ss.sTZD",
"status": 403,
"error": "unauthorized",
"message": "Unauthorized"
}Failure: Client error
Required fields, must not be blank.
{
"errors": [
{
"code": "MISSING",
"message": "Property [addressCountryCode] cannot be blank",
"path": "addressCountryCode",
"arguments": ["addressCountryCode"]
},
{
"code": "MISSING",
"message": "Please specify Address",
"path": "addressFirstLine",
"arguments": ["addressFirstLine"]
},
{
"code": "MISSING",
"message": "Property [addressCity] cannot be blank",
"path": "addressCity",
"arguments": ["addressCity"]
}
]
}Failure: Client error
If you send a body without detail, it will tell you that those fields are needed.
{
"errors": [
{
"code": "UNEXPECTED_ERROR",
"message": "Validation failed for argument...",
"arguments": []
}
]
}Failure: Client error
Certain countries require a postCode. If you try to create an address without a postCode for a country that requires it, you will get the following error.
{
"errors": [
{
"code": "UNEXPECTED_ERROR",
"message": "Validation failed for argument...",
"arguments": []
}
]
}Endpoint: /v1/profiles/{{business-profile-id}}/ubos
API reference: Create UBOs
Failure: Client error
UBOs must include a full object. Submitting a blank UBO object will result in the 400 error.
Unlike other APIs, this is the format for missing details or those that are otherwise errored. Please review this message for the details as to why the call failed.
{
"errors": [
{
"code": "BAD_REQUEST",
"message": "ApiError...",
"arguments": []
}
]
}Endpoint: /v3/profiles/{{business-profile-id}}/quotes
API reference: Create an authenticated quote
Failure: Client error
Invalid source or target currency codes.
{
"errors": [
{
"code": "CurrencyCode",
"message": "That wasn't a valid ISO-4217 currency code (like GBP, USD or EUR).",
"path": "targetCurrency",
"arguments": []
},
{
"code": "CurrencyCode",
"message": "That wasn't a valid ISO-4217 currency code (like GBP, USD or EUR).",
"path": "sourceCurrency",
"arguments": []
}
]
}Failure: Client error
Negative amount is not supported.
{
"errors": [
{
"code": "error.greaterThanZero",
"message": "Please type in a number that's larger than 0.",
"path": "sourceAmount",
"arguments": []
}
]
}Failure: Client error
Can't determine if source or target route because source and target amount are both specified. Please pick either sourceAmount or targetAmount, not both.
{
"errors": [
{
"code": "error.quote.amount.onlySingle",
"message": "Please only specify a source or target amount.",
"path": "sourceAmount",
"arguments": []
}
]
}Endpoint: /v1/accounts
API reference: Create a recipient account
Failure: Client error
First and last name is required for personal recipients, with at least 2 characters.
{
"timestamp": "YYYY-MM-DDThh:mm:ss.sTZD",
"errors": [
{
"code": "NOT_VALID",
"message": "Please enter the recipients first and last name.",
"path": "accountHolderName",
"arguments": [
"accountHolderName",
"John S"
]
}
]
}Failure: Client error
Bank account information is invalid (iban, swift, bank_code, account_number, etc).
{
"timestamp": "YYYY-MM-DDThh:mm:ss.sTZD",
"errors": [
{
"code": "NOT_VALID",
"message": "Please specify an IBAN.",
"path": "IBAN",
"arguments": [
"IBAN"
]
}
]
}Endpoint: /v1/transfers
API reference: Create transfer
Failure: Client error
Recipient address is required for this transfer because the source or the target currency route requires it.
{
"errors": [
{
"code": "INVALID_RECIPIENT",
"message": "Recipient address is mandatory for this payment, please update or create a new recipient.",
"arguments": []
}
]
}Endpoint: /v3/profiles/{{profileId}}/transfers/{{transferId}}/payments
API reference: Fund a Transfer
Failure: Client error
Not enough funds in balance.
{
"type": "BALANCE",
"status": "REJECTED",
"errorCode": "balance.payment-option-unavailable",
"errorMessage": null
}Failure: Server error
SCA Required. See Strong Customer Authentication & 2FA for more details.
{
"error": "unauthorized",
"message": "Unauthorized",
"path": null,
"status": 403,
"timestamp": "YYYY-MM-DDThh:mm:ss.sTZD"
}Endpoint: /v1/transfers/{{transferId}}/cancel
API reference: Cancel a Transfer
Failure: Client error
Attempting to cancel a completed transfer.
{
"errors": [
{
"code": "transfer.cancellation.not.allowed",
"message": "Transfer cannot be cancelled",
"arguments": []
}
]
}