Skip to content

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:

Status CodeMeaningWhen It's Returned
400Bad RequestInvalid or incomplete input
401UnauthorizedMissing or invalid authentication token
403ForbiddenAuthenticated but not authorized
404Not FoundResource doesn't exist or lacks translation
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected server error

🔹 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:

Previous page
Next page