Dashboard

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

CodeTypeDescription
200SuccessEverything worked as expected.
201SuccessResource created successfully.
204SuccessEverything worked as expected with empty body
400Bad requestRequest returned an error, detail in content.
401UnauthorizedInvalid authentication credentials.
404Not FoundThe requested resource was not found.
408TimeoutThe request timed out and was terminated by the server.
429Too Many RequestsToo many concurrent requests
500Server ErrorSomething 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 CodeHTTP CodeDescription
ATTRIBUTE_NOT_FOUND404No attribute was found with the informed key.
BRAZILIAN_BANK_NOT_FOUND404The informed brazilian bank was not found.
CANNOT_EXECUTE_ACTION422Generic error that occurs when the API is unable to execute a requested action.
IDEMPOTENT_ID_CONLICT409The informed idempotentIdhas already been used. Please use a different value.
INCOMPATIBLE_CURRENCY400The informed currencyis incompatible.
INVALID_DATA400Common error for data validation.
INVALID_DATE400The informed date is invalid.
INVALID_ENUM400The informed value is not a valid enum.
INVALID_MFA_CODE409The informed MFA Code is invalid.
INVALID_STATUS_CHANGE422Generic error that occurs when the resource's status cannot be updated to the specified status.
INVALID_UUID400The informed value is not a valid UUID.
MFA_NOT_ENABLED422The MFA is not enabled for the user.
MISSING_REQUIRED_HEADER400A required header is missing.
REQUIRED_ATTRIBUTE_IS_NULL422A required attribute is null.
RESOURCE_ALREADY_EXISTS409The resource matching the specified criteria already exists.
RESOURCE_NOT_FOUND404The resource matching the specified criteria was not found.