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

# Errors

> Understand how the TraxServer v5 API reports transport-level and business-logic errors

The TraxServer v5 API uses two distinct error mechanisms depending on the nature of the failure.

## HTTP Status Codes

Errors at the transport or authentication layer return a non-2xx HTTP status code:

| Status | Meaning      | Description                                                                                     |
| ------ | ------------ | ----------------------------------------------------------------------------------------------- |
| 200    | OK           | Request succeeded, or a business-logic validation failure occurred (check `result` in the body) |
| 400    | Bad Request  | Malformed request, invalid JSON, or an unacceptable argument                                    |
| 401    | Unauthorized | Missing or invalid session token                                                                |
| 403    | Forbidden    | Valid session but insufficient permissions for this operation                                   |
| 500    | Server Error | An unexpected internal error occurred                                                           |

### HTTP Error Response

Non-2xx responses return a simple JSON object:

```json theme={null}
{
  "error": "Session token is invalid or has expired."
}
```

## Business Logic Errors (HTTP 200)

Validation and business rule failures return HTTP 200 with a `result` of `"FAILURE"` in the response body. Always check the `result` field: a 200 does not guarantee success.

### Response Schema

<ResponseField name="result" type="string">
  `"SUCCESS"` or `"FAILURE"`
</ResponseField>

<ResponseField name="id" type="number | null">
  The ID of the created or updated resource, if applicable
</ResponseField>

<ResponseField name="dataObject" type="object | null">
  Additional data returned by the operation
</ResponseField>

<ResponseField name="errors" type="object | null">
  Present when `result` is `"FAILURE"` (see below)
</ResponseField>

### Error Object Schema

<ResponseField name="errors.fieldErrors" type="object">
  Map of field name to error. Each value has `type` and `errorMessage`.
</ResponseField>

<ResponseField name="errors.globalErrors" type="array">
  List of errors not tied to a specific field. Each item has `type` and `errorMessage`.
</ResponseField>

### Error Types

| Type              | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| `REQUIRED`        | A required field was missing or blank                       |
| `DUPLICATE`       | The value conflicts with an existing record                 |
| `INVALID_VALUE`   | The value is present but not acceptable                     |
| `INVALID_FORMAT`  | The value is not in the expected format                     |
| `INVALID_MAPPING` | The value does not map to a known resource                  |
| `NOT_MODIFIABLE`  | The field cannot be changed in its current state            |
| `DELETE`          | The resource cannot be deleted due to existing dependencies |
| `GENERAL`         | A non-field-specific validation failure                     |

### Example: Field Validation Failure

```json theme={null}
{
  "result": "FAILURE",
  "id": null,
  "dataObject": null,
  "errors": {
    "fieldErrors": {
      "amount": {
        "type": "REQUIRED",
        "errorMessage": "Amount is required."
      },
      "date": {
        "type": "INVALID_FORMAT",
        "errorMessage": "Date must be in YYYY-MM-DD format."
      }
    },
    "globalErrors": []
  }
}
```

### Example: Global Error

```json theme={null}
{
  "result": "FAILURE",
  "id": null,
  "dataObject": null,
  "errors": {
    "fieldErrors": {},
    "globalErrors": [
      {
        "type": "GENERAL",
        "errorMessage": "This transaction has already been reconciled and cannot be modified."
      }
    ]
  }
}
```

## Recommendations

* Always check the `result` field on 200 responses before treating an operation as successful.
* Use `fieldErrors` to surface inline validation messages to users.
* Use `globalErrors` for form-level or operation-level error banners.
* Log the full error response for troubleshooting: `type` is machine-readable and suitable for programmatic handling.