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

Copy
Copied
{
  "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