Errors and idempotency

Error envelope

All errors return a JSON body in this shape:

{
  "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

{
  "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

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "Request validation failed."
  }
}

422 — Schema conflict

{
  "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/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.

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

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.

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.

Get started

Guides

API reference

Errors and idempotency

Error envelope

Common error codes

401 — Invalid API key

422 — Validation error

422 — Schema conflict

429 — Rate limit

Idempotency

When to use `Idempotency-Key`

​Error envelope

​Common error codes

​401 — Invalid API key

​422 — Validation error

​422 — Schema conflict

​429 — Rate limit

​Idempotency

​When to use Idempotency-Key

Error envelope

Common error codes

401 — Invalid API key

422 — Validation error

422 — Schema conflict

429 — Rate limit

Idempotency

When to use `Idempotency-Key`