Table of Errors

Response Codes and Statuses

We understand the HTTP status codes are limited and cannot cover all types of situations required for proper error handling. The API uses the following definition as global status code for success and error responses, including in the message body the payload structure for describe the error structure.

Code	Status	Description
200	OK	The request was successfully completed.
201	Created	A new resource was successfully created.
400	Bad Request	The request was invalid.
401	Unauthorized	The request did not include an authentication token or the authentication token was expired.
403	Forbidden	The client did not have permission to access the requested resource.
404	Not Found	The requested resource was not found.
409	Conflict	The request could not be completed due to a conflict or a business rule constraint. For example, you cannot request a refund for a payment before it is settled.
500	Internal Server Error	The request was not completed due to an internal error on the server side.
503	Service Unavailable	The server was unavailable.

Error Structure

API operations may fail due to different circumstances during the processing flow. Next we present the general error structure.

{
    "error": {
        "name": "string",
        "message": "string",
        "details": [
            {
                "path": "string",
                "code": "string",
                "message": "string",
                "info": {
                    "pattern": "string"
                }
            }
        ],
        "frames": [],
        "date": "string"
    }
}

These fields are detailed bellow:

Field	Type	Description
error.name	string	An error group identifier, which can be reused for several `details.code`.
error.message	string	A high level description for the error group.
error.details.code	string	The low level identifier, which can be used to map errors to end-users if integrators wish to provide a lower-level explanation about an occurred error.
error.details.message	string	A low level textual description for the `details.code`.
error.details.path	string	The object field path that caused the error.
error.details.info.pattern	string	Describes the pattern in which the field failed to test.
error.date	string	Datetime of the error returned.
error.frames	string[]	List of error descriptions (DEPRECATED).

Errors Examples

Example #1: Authentication Error

{
  "error": {
    "name": "NOT AUTHORIZED",
    "message": "The authorization token is invalid",
    "details": [],
    "frames": [],
    "date": "2024-12-10T00:29:02.913Z"
  }
}

Example #2: Missing required parameter

{
	"error": {
    "name": "VALIDATION ERROR",
    "message": "The request body is invalid. See error object `details` property for more info.",
    "details": [
      {
        "path": "",
        "code": "required",
        "message": "must have required property 'value'",
        "info": {
          "missingProperty": "value"
        }
      }
    ],
    "frames": [],
    "date": "2024-12-10T00:27:22.579Z"
  }
}

Example #3: Providing invalid parameter value

{
  "error": {
    "name": "VALIDATION ERROR",
    "message": "The request body is invalid. See error object `details` property for more info.",
    "details": [
      {
        "path": "/pix_key_type",
        "code": "enum",
        "message": "must be equal to one of the allowed values",
        "info": {
          "allowedValues": [
            "CPF",
            "CNPJ",
            "PHONE",
            "EMAIL",
            "EVP"
          ]
        }
      }
    ],
    "frames": [],
    "date": "2024-12-10T00:30:14.279Z"
  }
}

Note: In the API section we explore another scenarios by presenting errors examples related to each endpoint individually.