{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/fr/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Error Handling","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"error-handling","__idx":0},"children":["Error Handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"-standard-http-status-codes","__idx":1},"children":["🔹 Standard HTTP Status Codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Trace One APIs return conventional HTTP status codes to indicate the result of a request:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status Code"},"children":["Status Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When It's Returned"},"children":["When It's Returned"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bad Request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid or incomplete input"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unauthorized"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or invalid authentication token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Forbidden"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authenticated but not authorized"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not Found"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource doesn't exist or lacks translation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Too Many Requests"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit exceeded"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Internal Server Error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unexpected server error"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"-error-schema-for-400-responses","__idx":2},"children":["🔹 Error Schema for 400 Responses"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"errors\": [\n    {\n      \"code\": \"ERROR_CODE\",\n      \"legacyCode\": null,\n      \"property\": \"fieldName\",\n      \"message\": \"Description of the error\",\n      \"detail\": null,\n      \"extensions\": {}\n    }\n  ],\n  \"type\": \"https://tools.ietf.org/html/rfc7231#section-6.5.1\",\n  \"title\": \"Bad Request\",\n  \"status\": 400,\n  \"detail\": null,\n  \"instance\": null,\n  \"extensions\": {}\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"-field-descriptions","__idx":3},"children":["🔸 Field Descriptions"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[]"]}," – An array of error objects representing one or more issues in the request.",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," – A unique error code identifying the type of error (can be validation, business logic, permission-related, etc.)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["property"]}," – The specific input field related to the error, if applicable."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," – Human-readable explanation of the error."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legacyCode"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["extensions"]}," – Reserved for advanced use or future expansion."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," – HTTP error metadata consistent with the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://tools.ietf.org/html/rfc7807"},"children":["RFC 7807 Problem Details"]}," format."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"-error-codes","__idx":4},"children":["🔹 Error Codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each API may define its own set of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["functional error codes"]}," to reflect domain-specific conditions. These are intended to be:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Machine-readable (for client-side error handling or workflows)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Stable and documented per API"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Mapped to meaningful user-facing messages by consumers"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example codes might include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRODUCT_NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_UNIT_OF_MEASURE"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_NOT_ELIGIBLE_FOR_ACTION"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MISSING_REQUIRED_SECTION"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Refer to the documentation for each specific API to see the list of supported error codes."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"-example","__idx":5},"children":["🔹 Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"errors\": [\n    {\n      \"code\": \"MISSING_REQUIRED_FIELD\",\n      \"property\": \"nutrientValue\",\n      \"message\": \"Nutrient value is required when declaring a nutrient\"\n    },\n    {\n      \"code\": \"INVALID_UNIT_OF_MEASURE\",\n      \"property\": \"uom\",\n      \"message\": \"Unit 'abc' is not supported for this nutrient\"\n    }\n  ],\n  \"status\": 400,\n  \"title\": \"Bad Request\",\n  \"type\": \"https://tools.ietf.org/html/rfc7231#section-6.5.1\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"-best-practices","__idx":6},"children":["🔹 Best Practices"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Always check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[]"]}," array to determine what went wrong."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," field for programmatic handling or localization."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log the full response for debugging and audit purposes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Avoid hardcoding error messages — use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," to drive application logic."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For related guidance, see:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/fr/getting-started/authentication"},"children":["Authentication & Access"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/fr/getting-started/rate-limits"},"children":["Rate Limits"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/fr/getting-started/coding-practices"},"children":["Coding Practices"]}]}]}]},"headings":[{"value":"Error Handling","id":"error-handling","depth":1},{"value":"🔹 Standard HTTP Status Codes","id":"-standard-http-status-codes","depth":2},{"value":"🔹 Error Schema for 400 Responses","id":"-error-schema-for-400-responses","depth":2},{"value":"🔸 Field Descriptions","id":"-field-descriptions","depth":3},{"value":"🔹 Error Codes","id":"-error-codes","depth":2},{"value":"🔹 Example","id":"-example","depth":2},{"value":"🔹 Best Practices","id":"-best-practices","depth":2}],"frontmatter":{"seo":{"title":"Error Handling"}},"lastModified":"2026-06-19T11:16:46.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/fr/getting-started/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}