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

# Errors and idempotency

> Error envelope, common status codes, and safe retries with Idempotency-Key.

## Error envelope

All errors return a JSON body in this shape:

```json theme={null}
{
  "error": {
    "type": "auth_error",
    "code": "invalid_api_key",
    "message": "Missing or invalid API key."
  }
}
```

| Field     | Description                                                                           |
| --------- | ------------------------------------------------------------------------------------- |
| `type`    | High-level category (e.g. `auth_error`, `invalid_request_error`, `rate_limit_error`). |
| `code`    | Machine-readable error code.                                                          |
| `message` | Human-readable description for debugging.                                             |

## Common error codes

| HTTP status | `code`                 | When it occurs                                                                       |
| ----------- | ---------------------- | ------------------------------------------------------------------------------------ |
| `401`       | `invalid_api_key`      | Missing, malformed, or revoked API key.                                              |
| `409`       | `idempotency_conflict` | `Idempotency-Key` reused with a different request body.                              |
| `413`       | `file_too_large`       | Uploaded file exceeds the size limit.                                                |
| `422`       | `validation_error`     | Required field missing or field fails type/format validation.                        |
| `422`       | `schema_conflict`      | Both `extraction_schema` and `extraction_schema_id` were provided. Provide only one. |
| `429`       | `rate_limited`         | Too many requests. See `Retry-After` header.                                         |

### 401 — Invalid API key

```json theme={null}
{
  "error": {
    "type": "auth_error",
    "code": "invalid_api_key",
    "message": "Missing or invalid API key."
  }
}
```

Check that your `Authorization: Bearer sk_test_...` header is present and that the key has not been revoked in the dashboard.

### 422 — Validation error

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "Request validation failed."
  }
}
```

### 422 — Schema conflict

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "schema_conflict",
    "message": "Provide either extraction_schema or extraction_schema_id, not both."
  }
}
```

### 429 — Rate limit

When you hit the rate limit, the response includes a `Retry-After` header indicating how many seconds to wait before retrying:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}
```

Always honour the `Retry-After` value. Retrying immediately will continue to be rejected.

## Idempotency

The `POST /v1/documents` endpoint accepts an `Idempotency-Key` header. When you provide a key:

* **First request:** processed normally; the response is stored alongside the key.
* **Duplicate request (same body):** the stored response is returned immediately — no new document is created and no second charge occurs. This is safe to use for retrying after network failures.
* **Duplicate request (different body):** returns `409 Conflict` with code `idempotency_conflict`.

```bash theme={null}
curl -X POST https://api.glialhealth.com/v1/documents \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: my-unique-job-id-7f3a2b" \
  -F file=@report.pdf \
  -F document_type=lab_report
```

<Note>
  Idempotency keys are scoped to your organisation and must be at most 255 characters. Use a UUID or a stable identifier from your own system (e.g. a database row ID) to avoid collisions.
</Note>

### When to use `Idempotency-Key`

Use it any time you cannot guarantee delivery:

* Retrying after a network timeout where you don't know if the server received the first request.
* Background jobs that may be requeued on failure.
* Any code path where submitting the same document twice would cause a duplicate charge or duplicate downstream processing.

Do **not** reuse the same key with a different file or form fields — that produces a `409`. Generate a fresh key for each logically distinct submission.