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 Text Explanation Action
0 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 Text Explanation Action
10001 Timeout error The request timed out as it took too long to respond. Try again.
10002 Unattended limit Too many requests in a given amount of time. Wait before retrying.
10003 Failed third party dependency An error occurred with a third party. Try again later.
10004 Internal server error Internal server error. Reach out to support.
10005 Retry limit reached Maximum number of retries reached. Check our API documentation on retry handling.
10006 Unprocessable entity Unable to process the instructions contained in the request. Check our API documentation.

11xxx Payload Validation

Code Text Explanation Action
11001 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 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 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 Text Explanation Action
12001 Invalid header type or syntax A header is not specified correctly. Check our API documentation for the header requirements for the request.
12002 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 Text Explanation Action
13001 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 Authorisation header is invalid The authorisation header is invalid. Check our API documentation to see how to provide the authorisation header.
13003 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 Forbidden You aren't permitted to make this request. Don't try again.

14xxx Resource Operation

Code Text Explanation Action
14001 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 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 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 Resource cannot be modified The resource cannot be updated. Don't try again.
14005 Resource conflict The resource has already been created. Don't try again.
14006 Resource duplication A resource with the same ID already exists. Use a different, unique value for ID and try again.
14007 Resource limit reached Maximum number of resources that can be created has been reached. Don't try again.

15xxx Payment Process

Code Text Explanation Action
15001 Payment authorisation is declined The payment failed user authorisation. Ask your end user to re-authorise.
15002 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 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 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 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 Unsupported scheme The payment scheme is unsupported. Check our documentation for the supported payment schemes. Select a supported payment scheme and try again.
15007 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 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.

17xxx Institution Interaction

Code Text Explanation Action
17001 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 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 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 Institution credentials error The institution does not recognise credentials provided. Check your credentials and try again.
17005 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 Text Explanation Action
18001 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 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 Text Explanation Action
19001 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