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.

CodeStatusDescription
200OKThe request was successfully completed.
201CreatedA new resource was successfully created.
400Bad RequestThe request was invalid.
401UnauthorizedThe request did not include an authentication token or the authentication token was expired.
403ForbiddenThe client did not have permission to access the requested resource.
404Not FoundThe requested resource was not found.
409ConflictThe 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.
500Internal Server ErrorThe request was not completed due to an internal error on the server side.
503Service UnavailableThe 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:

FieldTypeDescription
error.namestringAn error group identifier, which can be reused for several details.code.
error.messagestringA high level description for the error group.
error.details.codestringThe 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.messagestringA low level textual description for the details.code.
error.details.pathstringThe object field path that caused the error.
error.details.info.patternstringDescribes the pattern in which the field failed to test.
error.datestringDatetime of the error returned.
error.framesstring[]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.