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:

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