> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracefinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> How errors are structured and how to handle them.

## Overview

The Trace Finance API uses standard HTTP status codes and returns structured error responses. Every response includes an `X-Request-Id` header you can reference when contacting support.

## How it works

### Error response structure

All errors follow the same shape:

```json theme={"theme":"tokyo-night"}
{
  "code": "INVALID_DATA",
  "message": "The field 'amount.value' must be a positive integer.",
  "details": {}
}
```

| Field     | Type   | Description                                           |
| --------- | ------ | ----------------------------------------------------- |
| `code`    | string | Machine-readable error code for programmatic handling |
| `message` | string | Human-readable description of what went wrong         |
| `details` | object | Additional context (may be empty)                     |

### HTTP status codes

| Code  | Meaning               | When it happens                            |
| ----- | --------------------- | ------------------------------------------ |
| `200` | OK                    | Request succeeded                          |
| `201` | Created               | Resource was created                       |
| `204` | No content            | Request succeeded with no response body    |
| `400` | Bad request           | Invalid or malformed request data          |
| `401` | Unauthorized          | Missing or invalid authentication token    |
| `404` | Not found             | Resource does not exist                    |
| `408` | Request timeout       | Request took too long to process           |
| `409` | Conflict              | Idempotency key conflict or state conflict |
| `422` | Unprocessable entity  | Valid syntax but business rule violation   |
| `429` | Too many requests     | Rate limit exceeded                        |
| `500` | Internal server error | Unexpected server failure                  |

### Common error codes

| Code                         | HTTP status | Description                                                |
| ---------------------------- | ----------- | ---------------------------------------------------------- |
| `INVALID_DATA`               | 400         | Request body failed validation                             |
| `REQUIRED`                   | 400         | Required field is missing or blank                         |
| `INVALID_UUID`               | 400         | Field value is not a valid UUID                            |
| `INVALID_ENUM`               | 400         | Field value is not a valid enum option                     |
| `INVALID_DATE`               | 400         | Field value is not a valid date format                     |
| `INVALID_TYPE`               | 400         | Field value does not match the expected type               |
| `MISSING_REQUIRED_HEADER`    | 400         | Required HTTP header is missing                            |
| `INCOMPATIBLE_CURRENCY`      | 400         | Currency does not match the expected value                 |
| `INVALID_FILTER_FORMAT`      | 400         | Filter query parameter is malformed                        |
| `RESOURCE_NOT_FOUND`         | 404         | Requested resource does not exist                          |
| `IDEMPOTENT_ID_CONFLICT`     | 409         | Idempotency key was already used with a different request  |
| `RESOURCE_ALREADY_EXISTS`    | 409         | Resource with the given identifier already exists          |
| `ATTRIBUTE_MISMATCH`         | 409         | Field value conflicts with existing data                   |
| `INVALID_MFA_CODE`           | 409         | Provided MFA code is incorrect                             |
| `INVALID_STATUS_CHANGE`      | 422         | Resource cannot transition to the requested state          |
| `CANNOT_EXECUTE_ACTION`      | 422         | Action is not allowed in the current resource state        |
| `REQUIRED_ATTRIBUTE_IS_NULL` | 422         | Required attribute is missing or null                      |
| `MFA_NOT_ENABLED`            | 422         | Multi-factor authentication is required but not configured |

### Retry guidance

| Status code                | Should retry? | Strategy                                      |
| -------------------------- | ------------- | --------------------------------------------- |
| `400`, `401`, `404`, `422` | No            | Fix the request before retrying               |
| `408`, `429`               | Yes           | Back off and retry after the indicated period |
| `409`                      | Depends       | Check if the original request succeeded       |
| `500`                      | Yes           | Retry with exponential backoff                |

<Tip>
  Include the `X-Request-Id` from the response when opening a support ticket. This helps the team trace your request through the system.
</Tip>

## Examples

A validation error:

```json theme={"theme":"tokyo-night"}
{
  "code": "INVALID_DATA",
  "message": "The field 'amount.value' must be a positive integer.",
  "details": {
    "field": "amount.value"
  }
}
```

A resource not found:

```json theme={"theme":"tokyo-night"}
{
  "code": "RESOURCE_NOT_FOUND",
  "message": "Account with id 'abc-123' was not found.",
  "details": {}
}
```