API

Error handling

Overview

An error will always result in a response with a 4XX or 5XX HTTP status code.

The most common HTTP status codes returned by our API are:

Error format

The response will contain a JSON body conforming to RFC 9457, the “problem details” format.

ErrorResponse object

An ErrorResponse contains the following properties:

  • type - A URI reference that identifies the type of problem.
  • title - A short human-readable summary of the problem.
  • detail - A human-readable explanation of what went wrong.
  • status - A HTTP status code generated by the server.
  • code - A unique code representing the type of error that occurred.
  • errors (optional) - A list of ErrorDetail objects to accompany a problem details response.

Example:

1{
2  "type": "https://developer.yoco.com/docs/api/error-codes/not-found",
3  "title": "Not Found",
4  "detail": "The requested resource does not exist.",
5  "status": 404,
6  "code": "not_found"
7}

ErrorDetail object

An ErrorDetail contains the following properties:

  • detail - A human-readable explanation of what went wrong.
  • pointer (optional) - A JSON pointer to the request body property that caused the error.
  • parameter (optional) - The name of the query string or path parameter that caused the error.
  • code - A unique code representing the type of error that occurred.

Example:

1{
2  "detail": "The field is required.",
3  "pointer": "#/first_name",
4  "code": "missing_required_field"
5}

Error codes

Whilst an error will always be returned with a 4XX or 5XX HTTP status code, it will also contain a code that be used to uniquely identify the exact problem that occurred.

The following is an exhaustive list of error codes that our API can return. You can click on a specific error code to get more information and view an example response: