Skip to main content

Handling Common Errors

Error response format​

The error response format looks like this:

{
  "type": "validation_error",
  "errors": [
    {
      "code": "required",
      "detail": "This field is required.",
      "attr": "name"
    }
  ]
}
  • type: can be validation_error, client_error, or server_error.
  • code: A short string describing the error. You can use it to adapt your integration's behavior.
  • detail: user-friendly text describing the error. Usually in English, but may be localized.
  • attr: the field name when the error applies to a specific field (for example, in a validation_error), and null for non-validation errors when not applicable.

Common errors​

Some errors may appear on most of our endpoints. The following sections describe the most common ones. For more details, refer to the linked resources in OpenAPI.

403 Forbidden​

These errors are returned with status code 403 whenever authentication fails or a request is made to an endpoint without authentication information. These are the two possible errors:

{
    "type": "client_error",
    "errors": [
        {
            "code": "authentication_failed",
            "detail": "Incorrect authentication credentials.",
            "attr": null
        }
    ]
}
{
    "type": "client_error",
    "errors": [
        {
            "code": "not_authenticated",
            "detail": "Authentication credentials were not provided.",
            "attr": null
        }
    ]
}

405 Method Not Allowed​

This is returned when an endpoint is called with an unexpected HTTP method. For example, if updating a user requires a POST request and a PATCH is issued instead, this error is returned. Here's what it looks like:

{
    "type": "client_error",
    "errors": [
        {
            "code": "method_not_allowed",
            "detail": "Method \"PATCH\" not allowed.",
            "attr": null
        }
    ]
}

406 Not Acceptable​

This is returned if the Accept header is sent with a value other than application/json. Here's how the response would look:

{
    "type": "client_error",
    "errors": [
        {
            "code": "not_acceptable",
            "detail": "Could not satisfy the request Accept header.",
            "attr": null
        }
    ]
}

415 Unsupported Media Type​

This is returned when the request content type is not JSON. Here's how the response would look:

{
    "type": "client_error",
    "errors": [
        {
            "code": "unsupported_media_type",
            "detail": "Unsupported media type \"application/xml\" in request.",
            "attr": null
        }
    ]
}

500 Internal Server Error​

This is returned when the API server encounters an unexpected error. Here's how the response would look:

{
    "type": "server_error",
    "errors": [
        {
            "code": "error",
            "detail": "A server error occurred.",
            "attr": null
        }
    ]
}

Choose your guide​

I'm a Merchant

I want to collect payments or send money to my users.

I'm a Payment Provider

I have physical points and want to process Pago46 transactions.