Errors

You can tell if your request was successful by checking the status code in the API response. If a response is unsuccessful, use the HTTP status code and error message to understand what went wrong.

Status codes

Here is a list of the different categories of status codes returned by the Vatly API. Use these to understand if a request was successful.

Common status codes

Error responses

Whenever a request is unsuccessful, the Vatly API will return an error response with a human-readable message. Combine it with the HTTP status code to understand what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

{
  "message": "Resource not found."
}

Some errors also include an optional details object with structured context about the failure. Treat unknown keys as forward-compatible additions and branch on the HTTP status code rather than the shape of details.

{
  "message": "The requested resource was not found.",
  "details": {
    "resource_type": "checkout",
    "resource_id": "checkout_abc123"
  }
}

Validation errors

When a 422 status code is returned, the response includes field-specific error details:

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required."
    ],
    "products.0.id": [
      "The selected products.0.id is invalid."
    ]
  }
}

The errors object uses dot notation for nested fields. Each key maps to an array of error messages for that field.