Skip to main content

​
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."
  }
}
FieldDescription
typeHigh-level category (e.g. auth_error, invalid_request_error, rate_limit_error).
codeMachine-readable error code.
messageHuman-readable description for debugging.

​
Common error codes

HTTP statuscodeWhen it occurs
401invalid_api_keyMissing, malformed, or revoked API key.
409idempotency_conflictIdempotency-Key reused with a different request body.
413file_too_largeUploaded file exceeds the size limit.
422validation_errorRequired field missing or field fails type/format validation.
422schema_conflictBoth extraction_schema and extraction_schema_id were provided. Provide only one.
429rate_limitedToo 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.