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

# Errors

> Error handling and API error codes

## Error Response Format

All Enterprise API v2 errors return a consistent JSON structure:

```json theme={null}
{
  "error": {
      "code": "validation_error",
      "message": "patient.date_of_birth is required"
  }
}
```

## HTTP Status Codes

| Status | Description |
| - | - |
| `200` | Successful GET/PATCH/DELETE request |
| `201` | Successful POST request (resource created) |
| `400` | Invalid request body or validation errors |
| `401` | Missing or invalid API key |
| `403` | API key lacks required scope |
| `404` | Resource does not exist |
| `409` | Duplicate resource (e.g., webhook name already exists) |
| `422` | Semantic validation error |
| `429` | Request rate limit exceeded |
| `500` | Server-side error (contact support) |

## Error Codes

### `invalid_api_key`

**HTTP 401** - Missing or invalid API key

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

### `insufficient_scope`

**HTTP 403** - API key lacks required scope

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "Required scope: retrievals:write"
  }
}
```

### `validation_error`

**HTTP 400** - Request validation failed

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The title field is required"
  }
}
```

### `resource_not_found`

**HTTP 404** - Resource does not exist

```json theme={null}
{
  "error": {
    "code": "resource_not_found",
    "message": "Case not found"
  }
}
```

### `duplicate_name`

**HTTP 409** - Webhook name already exists within your organization

```json theme={null}
{
  "error": {
    "code": "duplicate_name",
    "message": "A webhook with this name already exists"
  }
}
```

### `rate_limited`

**HTTP 429** - Too many requests

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests, please try again later."
  }
}
```

## Limits

| Resource | Limit |
| - | - |
| Document upload (via presigned URL) | 5 GB per file |
| Request body (JSON) | 50 MB |

## Tips

### Use Webhooks Over Polling

Instead of polling for retrieval status, [set up webhooks](/guides/v2/webhooks) to receive real-time notifications when a request changes, needs action, or has records or invoices ready.

### Handle Partial Failures

When uploading multiple documents, track which uploads succeed/fail individually rather than treating the batch as all-or-nothing.

## Getting Help

If you encounter persistent errors, contact support at [contact@tavrn.ai](mailto:contact@tavrn.ai) with:

* Timestamp
* Full error response
* Steps to reproduce

## Next Steps

* [Set up webhooks](/guides/v2/webhooks)
* [View API schemas](/guides/v2/schemas)
* [Create your first retrieval](/guides/v2/get-started/first-retrieval)