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

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.


Requests that fail as a result of invalid input:


400 - Bad Request


X-Request-Id: 123e4567-e89b-12d3-a456-426614174000


  "code": "INVALID_DATA",
  "message": "Object contains invalid data",
  "details": {
    "errors": [
        "code": "REQUIRED",
        "message": "Parameter 'XXX' not found in request",
        "field": "body:xxx",
        "params": {}