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.
Updated 3 months ago