Error handling


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 errors only include the message field and may contain a tracingId.

Example error response:

"error": {
    "tracingId": "0c2d0973bdd24224a65e5d0f7d1b6154",
    "code": 424,
    "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
    "source": "INSTITUTION",
    "message": "The requested resource has not been found in the institution. We can help you on",
    "status": "NOT_FOUND"

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:


If there is no redirect back to your application via Yapily we recommend you contact Yapily to investigate why this has occurred. Yapily logs all the redirects received for customers using Yapily Connect's redirect URL

If there is no redirect back to your application directly from the bank, we recommend you check the payment status before retrying. Since you are using your own redirect URL, there is no way for Yapily to log any information on inbound redirects back to your application.