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

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