Errors
Ensuring consistent reliability and clear communication, our API employs conventional HTTP status codes to categorize responses and streamline error handling:
2xx
status codes signify successful processing of your request.4xx
status codes alert you to failures caused by incorrect information or validation errors in the request.5xx
status codes are reserved for instances where an issue has arisen within Trace's servers and systems.
To provide detailed error insights, every response is accompanied by a structured error object in the body, comprising the following fields:
{
"code": "error_code",
"message": "Error message describing the issue.",
"details": {
// Additional error details
}
}
code
: A string that uniquely identifies the specific error. This code serves as a categorization mechanism, allowing client applications to handle different types of errors programmatically.message
: A concise description providing an overview or summary of the error. This field offers a quick understanding of the issue.details
: A map providing additional information relevant to the error.
Additionally, each error response is accompanied by an X-Request-Id
header. This identifier is crucial for debugging, as it correlates with the specific process in our logs, allowing us to trace and address the root cause of the issue.
HTTP Status Code Summary
Code | Type | Description |
---|---|---|
200 | Success | Everything worked as expected. |
201 | Success | Resource created successfully. |
204 | Success | Everything worked as expected with empty body |
400 | Bad request | Request returned an error, detail in content. |
401 | Unauthorized | Invalid authentication credentials. |
404 | Not Found | The requested resource was not found. |
408 | Timeout | The request timed out and was terminated by the server. |
429 | Too Many Requests | Too many concurrent requests |
500 | Server Error | Something went wrong in Trace's infrastructure. |
Example:
Requests that fail as a result of invalid input:
Status:
400 - Bad Request
Header:
X-Request-Id: 123e4567-e89b-12d3-a456-426614174000
Body:
{
"code": "INVALID_DATA",
"message": "Object contains invalid data",
"details": {
"errors": [
{
"code": "REQUIRED",
"message": "Parameter 'XXX' not found in request",
"field": "body:xxx",
"params": {}
}
]
}
}
API Errors
Each API includes a GET /error
endpoint, which provides a comprehensive list of all potential errors that may be encountered during its use.
General Errors
Error Code | HTTP Code | Description |
---|---|---|
ATTRIBUTE_NOT_FOUND | 404 | No attribute was found with the informed key. |
BRAZILIAN_BANK_NOT_FOUND | 404 | The informed brazilian bank was not found. |
CANNOT_EXECUTE_ACTION | 422 | Generic error that occurs when the API is unable to execute a requested action. |
IDEMPOTENT_ID_CONLICT | 409 | The informed idempotentId has already been used. Please use a different value. |
INCOMPATIBLE_CURRENCY | 400 | The informed currency is incompatible. |
INVALID_DATA | 400 | Common error for data validation. |
INVALID_DATE | 400 | The informed date is invalid. |
INVALID_ENUM | 400 | The informed value is not a valid enum. |
INVALID_MFA_CODE | 409 | The informed MFA Code is invalid. |
INVALID_STATUS_CHANGE | 422 | Generic error that occurs when the resource's status cannot be updated to the specified status. |
INVALID_UUID | 400 | The informed value is not a valid UUID. |
MFA_NOT_ENABLED | 422 | The MFA is not enabled for the user. |
MISSING_REQUIRED_HEADER | 400 | A required header is missing. |
REQUIRED_ATTRIBUTE_IS_NULL | 422 | A required attribute is null. |
RESOURCE_ALREADY_EXISTS | 409 | The resource matching the specified criteria already exists. |
RESOURCE_NOT_FOUND | 404 | The resource matching the specified criteria was not found. |
Updated 3 months ago