Authentication & Errors

API Key Authentication

Public API-key endpoints use:

• Authorization: api-key <environment-api-key>

Applicable Endpoint Paths And Methods

This shared contract applies to:

1. POST /api/v1/extractFields
2. POST /api/v1/extraction-jobs
3. GET /api/v1/extraction-jobs/:id
4. GET /api/v1/extraction-jobs/:id/result
5. POST /api/v1/extractFieldsAsync (legacy polling-only route)

Legacy exception:

1. GET /api/v1/checkStatus/:guid is retained for older async clients and is not protected by apiKeyAuth

Request Schema

These endpoints require:

1. Authorization header using the api-key scheme
2. No additional auth body fields

Auth Header Rules

1. The scheme must be exactly api-key
2. A missing header is rejected
3. An empty token is rejected
4. A malformed token is rejected before the upstream auth lookup

Example:

Authorization: api-key <environment-api-key>

Response Schema

Successful responses vary by endpoint. Shared auth and runtime failures use the standard error shape.

Standard Error Shape

Most public runtime errors return:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "requestId": "request-id"
  }
}

The requestId is included on every error response and is useful for support and log correlation.

Example Request

curl -X GET "$BASE_URL/api/v1/extraction-jobs/$JOB_ID" \
  -H "Authorization: api-key $API_KEY"

Example Response

{
  "success": false,
  "error": {
    "code": "JOB_NOT_FOUND",
    "message": "Extraction job not found.",
    "requestId": "request-id"
  }
}

Common Status Codes

1. 400 Bad Request invalid body fields, unsupported delivery mode, or rejected webhook routing input
2. 401 Unauthorized missing or invalid API key
3. 404 Not Found template, filter-scoped resource, or job not found
4. 409 Conflict async result exists conceptually but is not retrievable in the requested state
5. 410 Gone async result expired after completion
6. 429 Too Many Requests request-level or polling rate limit triggered
7. 500 Internal Server Error unexpected server failure
8. 503 Service Unavailable dependent service unavailable
9. 504 Gateway Timeout auth or upstream extraction timeout

Common API-Key Errors

Missing API Key

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Missing API key",
    "requestId": "request-id"
  }
}

Unsupported Auth Scheme

{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_AUTH_SCHEME",
    "message": "Unsupported authentication scheme: Bearer",
    "requestId": "request-id"
  }
}

Invalid Or Expired API Key

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API key",
    "requestId": "request-id"
  }
}

Common Async Job Errors

Job Not Found

{
  "success": false,
  "error": {
    "code": "JOB_NOT_FOUND",
    "message": "Extraction job not found.",
    "requestId": "request-id"
  }
}

Result Not Ready

{
  "success": false,
  "error": {
    "code": "RESULT_NOT_READY",
    "message": "Extraction result is not ready yet.",
    "requestId": "request-id"
  }
}

Review Required

{
  "success": false,
  "error": {
    "code": "REVIEW_REQUIRED",
    "message": "Extraction result is awaiting manual review.",
    "requestId": "request-id"
  }
}

Job Failed

{
  "success": false,
  "error": {
    "code": "JOB_FAILED",
    "message": "Extraction job failed. Check the job status for details.",
    "requestId": "request-id"
  }
}

Result Expired

{
  "success": false,
  "error": {
    "code": "RESULT_EXPIRED",
    "message": "Extraction result is no longer available.",
    "requestId": "request-id"
  }
}

Poll Rate Limit

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT",
    "message": "Too many status checks, please try again shortly.",
    "requestId": "request-id"
  }
}

Legacy Route Error Shape

GET /api/v1/checkStatus/:guid is a compatibility route and does not fully match the canonical job error contract.

Examples:

{
  "success": false,
  "error": {
    "message": "Too many status checks, please try again shortly.",
    "code": "RATE_LIMIT"
  }
}

{
  "success": false,
  "message": "This job was not found. It may have expired or never existed."
}