Error Handling Guide - Yapily Docs

Yapily uses two error response formats. Check which format your product uses below.

Which Error Format Does My Product Use?

Enhanced Error Format
HTTP Status Code Format

Products using enhanced error format with structured issue codes:

Hosted Pages
Data Plus
Webhooks
User & Application Beneficiaries
VRP (only for payload validation)
Bulk Payment (only for payload validation)

Scroll down to the Enhanced Error Format Documentation section for details.

Enhanced Error Format Documentation

Used by: Hosted Pages, Data Plus, Webhooks, User & Application Beneficiaries, VRP (payload validation), Bulk Payment (payload validation)

This format provides detailed error information with structured issue codes. For other operations, see HTTP Status Code Format Documentation.

Introduction

When you make an API call to Yapily and there is an error, you will receive an error response including error codes and message fields to help you diagnose and solve the error. We recommend building your error handling logic around the Error Codes and Message properties in the response, as these provide the most specific information about the underlying issue.

Response Structure

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.

When an error occurs, you’ll receive a response with an error object containing an issues array:

{
  "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	Identifies the specific error that has occurred. See error code catalog
`issues.message`	string	No	Message associated with the error

If you need to contact support, we advise you share the error response with us, or 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 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 an 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 represents 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
15009	400	Verification of payee rejected	The beneficiary or beneficiaries failed the Verification of Payee (VOP) check	Verify that all payment recipients have successfully passed the VOP check before resubmitting. See Verification of Payee documentation

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
16002	204	There are no transactions available for the selected time period	No transactions were found for the time period specified	Adjust date parameters and try again
16003	424	The provided dates are outside the consent fetch window	The dates provided are outside of the consent fetch window	Narrow your date parameters and try again

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 with Support 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
17006	424	Institution Operation Timeout	There was a timeout due to a slow bank response. This is related to how long the financial institution takes to process our requests, hence the timeout	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

Code	Http Status Code	Text	Explanation	Action
19001	400	Consent authorisation is declined	Consent provided is not authorised for the triggered operation	Check if the consent is authorised for the triggered operation or if the consent has an authorised state

20xxx Webhook Validation

Code	Http Status Code	Text	Explanation	Action
20001	400	Invalid callback URL syntax	The callback URL must not contain query parameters	Provide the query parameters in the metadata field of the request

21xxx VRP Mandate Validation

Code	Http Status Code	Text	Explanation	Action
21001	400	Mandate either not yet active or already expired	Payment not authorised at this time	Check mandate control parameters, then either wait until mandate becomes active or request new VRP authorisation from the user
21002	500	Mandate not found	Payment could not be validated because its mandate was not found	Reach out to support
21003	400	Payment amount exceeds authorised limit per payment	Payment will exceed maximum amount per payment, specified at VRP authorisation	Submit a smaller payment amount or request new VRP authorisation from the user with greater limits
21004	400	Payment amount exceeds authorised limit over some period	Payment will exceed some maximum amount per frequency, specified at VRP authorisation	Submit a smaller payment amount or wait until the next period starts or request new VRP authorisation from the user with greater limits

HTTP Status Code Format Documentation

Used by: Financial Data (Accounts, Transactions, Balances), Single Payments, Bulk Payments, Authorisations, Consents, Institutions & Users, Variable Recurring Payments (VRPs)

Introduction

After sending an API request, you may receive a response back including an error object. You should build logic to account for any API errors that a request or the system may return. You may also receive an authorisation error after the end user’s redirection to the bank. You should log the query parameters returned from the redirect to understand any failures that occur.

Error Response Fields

All errors are returned with the same structure. The response object contains the following fields for 4XX errors:

Field	Type	Required	Description
`code`	integer	Yes	Numeric HTTP status code associated with the error
`status`	string	Yes	Description of the HTTP status error type
`message`	string	Yes	Description of the exact error, including Yapily support URL
`institutionError`	object	No	Error details provided by the institution when the institution is the source of the error
`source`	string	No	Indicates who triggered the failure and therefore can take action to correct it. One of: USER (the PSU), INSTITUTION (bank side error) or YAPILY
`tracingId`	string	No	A unique ID assigned by Yapily to use as a reference. Provide this if you contact our support team for assistance

500 Internal Server Errors return a simplified structure containing only the message field and tracingId:

{
  "error": {
    "tracingId": "8f3c6d2a1b4e5f9g0h1i2j3k",
    "message": "Internal server error. Please contact support with this tracing ID."
  }
}

Example 4XX error response:

{
  "error": {
    "tracingId": "74b13ce8ed51419f92c5d609e04532de",
    "code": 424,
    "status": "FAILED_DEPENDENCY",
    "message": "The requested resource has not been found in the institution. We can help you on https://support.yapily.com/",
    "source": "INSTITUTION",
    "institutionError": {
      "errorMessage": "{\"Code\":\"400 BadRequest\",\"Id\":\"3517bfc2-c3ee-4f2f-b4f8-12f62478e0d1\",\"Message\":\"No Resource found\",\"Errors\":[{\"ErrorCode\":\"UK.OBIE.Resource.NotFound\",\"Message\":\"No resource found corresponding to the consent id\"}]}",
      "httpStatusCode": 400
    }
  }
}

If you need to contact support, include the tracingId so we can identify your request.

HTTP Response Codes

Yapily uses standard HTTP response codes to indicate the success or failure of an API request.

HTTP status code	HTTP status message	Description	Action
200	OK	Everything worked as expected	-
201	Created	A resource was created successfully	-
400	Bad Request	The receiving server cannot understand the request because of malformed syntax or a missing field	Check and modify the request before repeating
401	Unauthorised	Missing, incomplete or invalid credentials (e.g. key, secret, auth token, certificate)	Input valid and complete authentication credentials
403	Forbidden	Insufficient permissions to process the request	You don’t have permissions to perform the request
404	Not Found	Resource not found	It’s not possible to retrieve the resource you requested. This could be the result of an incorrect URL or the resource doesn’t exist
406	Not Acceptable	Unacceptable response content	Include JSON in the list of accepted response values for your application
409	Conflict	Request couldn’t be completed due to conflict with current state of target resource (e.g. attempting to create a user that already exists)	Consult the message returned in the response body to find the source of conflict
424	Failed Dependency	Unable to complete the required operations with the institution	This indicates a bank side error
429	Too Many Requests	Too many requests in a given amount of time	Wait before retrying
500	Internal Server Error	Server could not process the request	Something went wrong on Yapily’s end
501	Not Implemented	The requested feature is unavailable for the specified institution	Confirm which features are supported by each institution

Authorisation Errors

Authorisation errors can occur when the user is redirected to the institution to provide their consent. If the user doesn’t provide their consent or there is an issue with the institution, the failure response is returned as query parameters. We recommend you log the query parameters received on your callback URL or redirect URL for all requests so you have access to the information explaining what has occurred. For more information see:

Handling Missing Callbacks

Callbacks may not reach your application due to network issues, browser restrictions, or bank-side errors. When this happens, users can become stuck in incomplete flows. To prevent this, poll the consent or payment status endpoint to check if the authorisation completed successfully. Implementation Steps:

Set a timeout: Wait 10-15 minutes after redirecting the user to the bank
Start polling: If no callback is received, poll at increasing intervals: 1s, 2s, 3s, 5s, 8s, 13s, 21s, 34s. Stop after 8 attempts (~1.5 minutes total).
Handle the result based on the status returned:
- AUTHORIZED - Continue your flow
- REJECTED - Show error message to user
- AWAITING_AUTHORIZATION - User may still be completing authorisation on the bank screen or app
- FAILED - Show error details

Example Implementation:

async function pollConsentStatus(consentId: string, maxAttempts: number = 9): Promise<string> {
  const delays = [1000, 1000, 2000, 3000, 5000, 8000, 13000, 21000, 34000]; // Fibonacci sequence in milliseconds

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    await sleep(delays[attempt]);

    const status = await getConsentStatus(consentId);

    // If authorisation complete, return status
    if (status !== 'AWAITING_AUTHORIZATION') {
      return status;
    }
  }

  // Final check after all attempts
  return await getConsentStatus(consentId);
}

If Using Yapily Connect (https://auth.yapily.com/): Contact Yapily Support with your consent or payment ID if you receive no callback. We log all redirects to our URL and can investigate. If Using Your Own Redirect URL: You must implement the polling strategy above. Yapily cannot log redirects to your URL, so ensure your endpoint has comprehensive logging to diagnose failures.

When to Contact Support

If you encounter errors that you cannot resolve:

Collect the error details:
- tracingId from the error response
- Full error response body
- Request details (endpoint, parameters)
Review the documentation:
- Check the error code catalog above
- Verify your request format matches our API Reference
- Review product-specific documentation
Contact support:
- Visit our Support page
- Include the tracingId in your message
- Provide context about what you’re trying to accomplish

Our support team can help investigate issues and provide guidance on resolving errors.

Learn

Build

Payments

Data

Hosted Pages

Resources

Error Handling

Which Error Format Does My Product Use?

Enhanced Error Format Documentation

Introduction

Response Structure

Error Code Structure

Error Catalogue

Unknown Error

10xxx Pre-Flight Checks

11xxx Payload Validation

12xxx Request Header Validation

13xxx Authorisation Process

14xxx Resource Operation

15xxx Payment Process

16xxx Transactions Retrieval Process

17xxx Institution Interaction

18xxx Query Parameters

20xxx Webhook Validation

21xxx VRP Mandate Validation

HTTP Status Code Format Documentation

Introduction

Error Response Fields

HTTP Response Codes

Authorisation Errors

Handling Missing Callbacks

When to Contact Support

​Which Error Format Does My Product Use?

​Enhanced Error Format Documentation

​Introduction

​Response Structure

​Error Code Structure

​Error Catalogue

​Unknown Error

​10xxx Pre-Flight Checks

​11xxx Payload Validation

​12xxx Request Header Validation

​13xxx Authorisation Process

​14xxx Resource Operation

​15xxx Payment Process

​16xxx Transactions Retrieval Process

​17xxx Institution Interaction

​18xxx Query Parameters

​19xxx Consent Processing

​20xxx Webhook Validation

​21xxx VRP Mandate Validation

​HTTP Status Code Format Documentation

​Introduction

​Error Response Fields

​HTTP Response Codes

​Authorisation Errors

​Handling Missing Callbacks

​When to Contact Support

Which Error Format Does My Product Use?

Enhanced Error Format Documentation

Introduction

Response Structure

Error Code Structure

Error Catalogue

Unknown Error

10xxx Pre-Flight Checks

11xxx Payload Validation

12xxx Request Header Validation

13xxx Authorisation Process

14xxx Resource Operation

15xxx Payment Process

16xxx Transactions Retrieval Process

17xxx Institution Interaction

18xxx Query Parameters

19xxx Consent Processing

20xxx Webhook Validation

21xxx VRP Mandate Validation

HTTP Status Code Format Documentation

Introduction

Error Response Fields

HTTP Response Codes

Authorisation Errors

Handling Missing Callbacks

When to Contact Support