# 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 Code | Meaning | When It's Returned |
|  --- | --- | --- |
| `400` | Bad Request | Invalid or incomplete input |
| `401` | Unauthorized | Missing or invalid authentication token |
| `403` | Forbidden | Authenticated but not authorized |
| `404` | Not Found | Resource doesn't exist or lacks translation |
| `429` | Too Many Requests | Rate limit exceeded |
| `500` | Internal Server Error | Unexpected 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.

```json
{
  "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](https://tools.ietf.org/html/rfc7807) 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

```json
{
  "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](/getting-started/authentication)
- [Rate Limits](/getting-started/rate-limits)
- [Coding Practices](/getting-started/coding-practices)