Error handling

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.

note

500 errors only include the message field and may contain a tracingId.

Example error response:

Copy

Copied

"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 https://support.yapily.com/",
    "status": "NOT_FOUND"
}

info

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:

Note:

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 https://auth.yapily.com/.

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.