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

# Errors

> API error codes and how to handle them

## Error Format

```json theme={null}
{
  "error": {
    "code": "error_code",
    "message": "Human-readable message",
    "details": []
  }
}
```

## Error Codes

### `400 Bad Request`

**Code**: `validation_error` or `invalid_json`

Request failed validation. Check the `details` array for specifics.

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      {
        "field": "context.billable_customer_id",
        "code": "required",
        "message": "billable_customer_id is required"
      }
    ]
  }
}
```

**Field Error Codes:**

| Code             | Meaning                        |
| ---------------- | ------------------------------ |
| `required`       | Field is required but missing  |
| `invalid_type`   | Field has wrong type           |
| `invalid_value`  | Field value not in allowed set |
| `too_small`      | Value below minimum            |
| `too_large`      | Value above maximum            |
| `invalid_format` | Value format is invalid        |

Common causes:

* Missing required fields (`provider`, `model`, `usage`, `context.billable_customer_id`)
* Invalid enum values for `provider`
* Request body isn't valid JSON

### `401 Unauthorized`

**Code**: `unauthorized`

API key is missing or invalid.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}
```

Check:

* `X-Api-Key` header is present
* Key is correct and active in your dashboard

### `207 Multi-Status`

Some transactions succeeded, some failed. Check `results` for details.

```json theme={null}
{
  "status": "partial_success",
  "events_queued": 1,
  "events_failed": 1,
  "results": [
    { "transaction_index": 0, "message_id": "abc123" },
    { "transaction_index": 1, "error": "billable_customer_id is required" }
  ]
}
```

### `500 Internal Server Error`

**Code**: `internal_error`

Server-side issue. Safe to retry.

```json theme={null}
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  }
}
```