Error Handling

This guide explains how Trace One APIs communicate errors in response to failed requests. We follow standard HTTP status codes and extend them with a consistent error payload that supports both technical and functional error reporting.

🔹 Standard HTTP Status Codes

Trace One APIs return conventional HTTP status codes to indicate the result of a request:

🔹 Error Schema for 400 Responses

For structured error reporting, Trace One APIs use a consistent error schema in the response body. This is especially useful for capturing domain-specific and functional errors in addition to basic validation failures.

{
  "errors": [
    {
      "code": "ERROR_CODE",
      "legacyCode": null,
      "property": "fieldName",
      "message": "Description of the error",
      "detail": null,
      "extensions": {}
    }
  ],
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": null,
  "instance": null,
  "extensions": {}
}

🔸 Field Descriptions

• errors[] – An array of error objects representing one or more issues in the request.
  • code – A unique error code identifying the type of error (can be validation, business logic, permission-related, etc.).
  • property – The specific input field related to the error, if applicable.
  • message – Human-readable explanation of the error.
  • legacyCode, detail, extensions – Reserved for advanced use or future expansion.
• status, title, type – HTTP error metadata consistent with the RFC 7807 Problem Details format.

🔹 Error Codes

Each API may define its own set of functional error codes to reflect domain-specific conditions. These are intended to be:

• Machine-readable (for client-side error handling or workflows)
• Stable and documented per API
• Mapped to meaningful user-facing messages by consumers

Example codes might include:

• PRODUCT_NOT_FOUND
• INVALID_UNIT_OF_MEASURE
• USER_NOT_ELIGIBLE_FOR_ACTION
• MISSING_REQUIRED_SECTION

Refer to the documentation for each specific API to see the list of supported error codes.

🔹 Example

{
  "errors": [
    {
      "code": "MISSING_REQUIRED_FIELD",
      "property": "nutrientValue",
      "message": "Nutrient value is required when declaring a nutrient"
    },
    {
      "code": "INVALID_UNIT_OF_MEASURE",
      "property": "uom",
      "message": "Unit 'abc' is not supported for this nutrient"
    }
  ],
  "status": 400,
  "title": "Bad Request",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1"
}

🔹 Best Practices

• Always check the errors[] array to determine what went wrong.
• Use the code field for programmatic handling or localization.
• Log the full response for debugging and audit purposes.
• Avoid hardcoding error messages — use the code to drive application logic.

For related guidance, see:

• Authentication & Access
• Rate Limits
• Coding Practices