Error codes
Learn more about Yapily's error codes and how to resolve them.
Introduction
info
The error codes are not supported by all our endpoints. Please check the API Reference for an up-to-date specification of the API.
When you make an API call to Yapily and there is an error, you will receive an error response including an error code and message field to help you diagnose and solve the error.
In general, we recommend that you build your integration error handling logic around Error Codes
and Message
payload properties. These properties and their values are more indicative of the underlying error.
Error Response Structure
info
When receiving an error response, it is important to note that there might be multiple error codes included. To effectively troubleshoot the problem, you need to consider all of these error codes.
Sample Error Response
{
"error": {
"tracingId": "0c2d0973bdd24224a65e5d0f7d1b6154",
"code": 400,
"status": "BAD_REQUEST",
"supportUrl": "https://support.yapily.com/",
"source": "YAPILY",
"issues": [
{
"type": "INVALID_PAYLOAD",
"code": "11001",
"message": "Timeout error"
},
{
"type": "INVALID_PAYLOAD",
"code": "11003",
"message": "Failed third party dependency"
}
]
}
}
Field | Type | Required | Description |
---|---|---|---|
tracingId |
string | Yes | A unique ID assigned by Yapily to use as a reference. Provide this if you contact our support team for assistance |
code |
integer | Yes | Numeric HTTP status code associated with the error |
status |
string | Yes | Description of the HTTP status error type |
supportUrl |
string | Yes | The Yapily support URL where further help and support can be accessed |
source |
string | Yes | Indicates who triggered the failure and therefore can take action to correct it. One of: USER (the PSU), INSTITUTION (bank side error) or YAPILY |
issues |
array of objects | No | All issues that have been experienced whilst processing the request |
issues.type |
string | Yes | Identifies the error category |
issues.code |
string | Yes | Identified the specific error that has occurred. See error code numbers |
issues.message |
string | No | Message associated with the error |
info
If you need to contact support, we advise you share the error response with us, if not possible include the tracingId
and the error codes
so we can identify your request and trace the origin of the issue.
Error Code Structure
The 5-digit error codes are structured as follows:
- First 2 digits : Represent the group of the error.
- Last 3 digits : Represent the specific error within the group.
Error catalogue
Below is a list of possible error issue codes, along with additional information about how to resolve them.
Unknown Error
we will be sending this error if we encountered a error we haven't seen yet and does not have a handler on our side, if you see this error please contact support.
Code | Http Status Code | Text | Explanation | Action |
---|---|---|---|---|
0 | 400 | Unknown error | An unknown error occurred | Try again later |
10xxx Pre-Flight Checks
This error group represent issues that occur either before payload and header validation, or during third-party calls that use the data from the original request.
Code | Http Status Code | Text | Explanation | Action |
---|---|---|---|---|
10001 | 408 | Timeout error | The request timed out as it took too long to respond | Try again |
10002 | 429 | Unattended limit | Too many requests in a given amount of time | Wait before retrying |
10003 | 424 | Failed third party dependency | An error occurred with a third party | Try again later |
10004 | 500 | Internal server error | Internal server error | Reach out to support |
10005 | 422 | Retry limit reached | Maximum number of retries reached | Check our API documentation on retry handling |
10006 | 422 | Unprocessable entity | Unable to process the instructions contained in the request | Check our API documentation |
11xxx Payload Validation
Code | Http Status Code | Text | Explanation | Action |
---|---|---|---|---|
11001 | 400 | The server could not understand the request due to invalid format or syntax | Something in the request is not specified correctly | Check our API documentation |
11002 | 400 | Invalid parameter | A parameter is not specified correctly, for example too many characters | Check our API documentation for the field requirements for the request |
11003 | 400 | Missing parameter | A required parameter is not included in the request | Check our API documentation to identify the required parameters for the request |
12xxx Request Header Validation
Code | Http Status Code | Text | Explanation | Action |
---|---|---|---|---|
12001 | 400 | Invalid header type or syntax | A header is not specified correctly | Check our API documentation for the header requirements for the request |
12002 | 400 | Missing mandatory header | A required header is missing from the request | Check our API documentation to see which headers are required for the request |
13xxx Authorisation Process
Code | Http Status Code | Text | Explanation | Action |
---|---|---|---|---|
13001 | 401 | Authorisation header is missing | The authorisation header is missing from the request | All requests to Yapily API require basic authentication, provide your application username and password in the authorisation header for the request |
13002 | 403 | Authorisation header is invalid | The authorisation header is invalid | Check our API documentation to see how to provide the authorisation header |
13003 | 401 | Authorisation failed | You don't have permissions to make this request. For example, your credentials have expired | View and manage your credentials in the Yapily Console |
13004 | 403 | Forbidden | You aren't permitted to make this request | Don't try again |
14xxx Resource Operation
Code | Http Status Code | Text | Explanation | Action |
---|---|---|---|---|
14001 | 404 | Resource not found | It's not possible to retrieve the resource you requested | The resource likely doesn't exist or the ID you provided is incorrect |
14002 | 400 | Resource not matching | It's not possible to update the resource as the information provided doesn't match the resource | Check the information supplied in the request is accurate for that resource |
14003 | 400 | Resource not valid | The resource request is incomplete or holds invalid data | Check our API documentation to see how to submit data for the resource. |
14004 | 400 | Resource cannot be modified | The resource cannot be updated | Don't try again |
14005 | 409 | Resource conflict | The resource has already been created | Don't try again |
14006 | 409 | Resource duplication | A resource with the same ID already exists | Use a different, unique value for ID and try again |
14007 | 406 | Resource limit reached | Maximum number of resources that can be created has been reached | Don't try again |
15xxx Payment Process
Code | Http Status Code | Text | Explanation | Action |
---|---|---|---|---|
15001 | 400 | Payment authorisation is declined | The payment failed user authorisation | Ask your end user to re-authorise |
15002 | 400 | Destination and source account currency must match | The benefactor and beneficiary account must be of the same currency type | Use a different payment scheme that allows for different currency types |
15003 | 400 | Source account has insufficient funds to complete transfer | The benefactor's account doesn't have enough funds to process the transfer | Alert the benefactor that they have insufficient funds. Try again after funds have been increased |
15004 | 400 | Client must be the parent client for this application | The application is not a child of the parent application submitted | Check the application used before trying again |
15005 | 400 | Exceeded payment limit | The request is higher than the specified payment limit | Reduce the payment value to below the payment limit and try again |
15006 | 400 | Unsupported scheme | The payment scheme is unsupported | Check our documentation for the supported payment schemes. Select a supported payment scheme and try again |
15007 | 400 | Destination account must be different from the source account | The benefactor and beneficiary account details cannot be the same | Check the payer and payee account details and make sure they are different |
15008 | 400 | The payment you wish to return must be of type PAYOUT with status COMPLETED | You can only refund payments of type PAYOUT and status COMPLETED | Check our documentation on refunds. If type PAYOUT, try again when the status is COMPLETED |
16xxx Transactions Retrieval Process
Code | Http Status Code | Text | Explanation | Action |
---|---|---|---|---|
16001 | 424 | Institution historical data retrieve timeout | The request timed out when fetching historical data from the Institution | Limit the requested transaction period |
17xxx Institution Interaction
Code | Http Status Code | Text | Explanation | Action |
---|---|---|---|---|
17001 | 404 | The institution is not active in provided country | The institution is not currently available in the country you requested | You are not able to access the institution in this country at this time |
17002 | 404 | The institution is not registered against your application | You must register your application with each institution before you can use Yapily's API to access data or make a payment with that institution | You can manage and register with institutions in your Yapily Console check our documentation on registration. If you are a Yapily Connect customer, get in touch at support@yapily.com and we can add the institution to your application |
17003 | 404 | The institution does not match the payment initiation values | There is a mismatch between institution data submitted at payment initiation and data we hold about the institution | Check your submission data and try again |
17004 | 424 | Institution credentials error | The institution does not recognise credentials provided | Check your credentials and try again |
17005 | 424 | Unsupported resource | The institution resource is not supported | Check our documentation for the supported resource. Select a supported resource and try again |
18xxx Query Parameters
Code | Http Status Code | Text | Explanation | Action |
---|---|---|---|---|
18001 | 400 | Invalid query parameter | A query parameter is not specified correctly | Check our API documentation for how to specify the query parameter for the request |
18002 | 400 | Missing query parameter | A query parameter is missing from the request | Check our API documentation to see the required query parameter for the request |
19xxx Consent Processing
Code | Http Status Code | Text | Explanation | Action |
---|---|---|---|---|
19001 | 400 | Consent authorisation is declined | Consent provided is not authorise for the triggered operation | check if the consent is authorised for the triggered operation or if the consent has an authorised state |