ALK API

Errors & Escalation

This page explains how Alk returns errors, how to debug common issues, and what information to include when escalating to your Alk account team.

Error shapes

Most non-validation errors use a simple payload:


Code
{ "detail": "Human-readable message" }

Examples from the API schema:

400 Bad Request (BadRequestError): {"detail":"Invalid request"}
404 Not Found (NotFoundError): {"detail":"Workflow not found"}

422 Validation errors

When request parameters or bodies fail validation, Alk returns HTTPValidationError:


Code
{
  "detail": [
    {
      "loc": ["body", "collection_id"],
      "msg": "field required",
      "type": "missing"
    }
  ]
}

Where:

loc: which part of the request failed (path/query/body + field name / index)
msg: what went wrong (human readable)
type: a machine-ish error type (useful for grouping)

Common issues and fixes

Authentication failures (401/403)

Confirm you’re sending Authorization: Bearer <api_key> on every request.
Ensure you’re using the right key type (alk_test_… vs alk_live_…) for the environment.
Verify your key has the required scopes for the endpoint you’re calling.

Workflow not found (404)

Verify the workflow_id is correct and belongs to your entity.
Confirm you didn’t accidentally use a test workflow ID with a live key (or vice versa).

Upload issues

For signed uploads, ensure you confirm after uploading to signed URLs (/documents/confirm).
For collection uploads, ensure you pass either collection_id or collection_name consistently.

Extraction appears “stuck”

Check is_extracting and extraction_status on the workflow response.
Use the extractions endpoints to list results and confirm pagination rather than assuming a single response will include everything.

Rate limiting / throttling

We rate-limit every API endpoint to keep the platform stable and fast for everyone building on it. When limits are exceeded, the API returns HTTP 429 Too Many Requests.

Rate limits may be enforced using a combination of signals: API credentials, account identifiers, IP addresses, request volume, and concurrent request behaviour. Your integration should ensure that both request throughput and concurrent in-flight requests remain within supported limits.

Managing rate limits

Design workflows to minimise unnecessary API calls.
Use caching and batching where appropriate to reduce the frequency of requests.
Implement idempotency to prevent duplicates during retries.
Prefer webhooks and event-driven integrations instead of aggressive polling (polling should be a last resort).
Limit request concurrency and avoid unbounded parallel processing patterns.
Ensure your application gracefully handles non-JSON error responses returned by intermediary systems.

Retry strategy (429 / intermediary throttling)

If you receive an HTTP 429 response:

Stop sending immediate follow-up requests after throttling occurs.
Retry using exponential backoff with randomized jitter (e.g. wait 1s, then 2s, then 4s, adding a small random offset each time).
Increase the delay gradually with each attempt.
Set retry limits to avoid infinite retry loops.
Avoid high-frequency polling or uncontrolled concurrent retries that may continue triggering restrictions.

Retries may help recover from temporary traffic bursts. Repeated rate-limit responses usually indicate that request patterns, concurrency levels, or polling strategies should be redesigned.

Escalation: what to send

When you escalate to your Alk account team, include:

Workflow ID and (if relevant) collection ID / document ID
Endpoint + method (e.g. GET /api/v1/workflows/{workflow_id}/…)
Timestamp (with timezone) and environment (test or live)
Request ID / correlation ID (if your system adds one)
HTTP status code and the full response body
A sanitized request (headers without secrets; body with sensitive fields redacted)
Expected vs actual behavior

If possible, attach a minimal reproducible cURL command.

Last modified on June 6, 2026

Workflows Best Practices

ALK API

Errors & Escalation

This page explains how Alk returns errors, how to debug common issues, and what information to include when escalating to your Alk account team.

Error shapes

Most non-validation errors use a simple payload:


Code
{ "detail": "Human-readable message" }

Examples from the API schema:

400 Bad Request (BadRequestError): {"detail":"Invalid request"}
404 Not Found (NotFoundError): {"detail":"Workflow not found"}

422 Validation errors

When request parameters or bodies fail validation, Alk returns HTTPValidationError:


Code
{
  "detail": [
    {
      "loc": ["body", "collection_id"],
      "msg": "field required",
      "type": "missing"
    }
  ]
}

Where:

loc: which part of the request failed (path/query/body + field name / index)
msg: what went wrong (human readable)
type: a machine-ish error type (useful for grouping)

Common issues and fixes

Authentication failures (401/403)

Confirm you’re sending Authorization: Bearer <api_key> on every request.
Ensure you’re using the right key type (alk_test_… vs alk_live_…) for the environment.
Verify your key has the required scopes for the endpoint you’re calling.

Workflow not found (404)

Verify the workflow_id is correct and belongs to your entity.
Confirm you didn’t accidentally use a test workflow ID with a live key (or vice versa).

Upload issues

For signed uploads, ensure you confirm after uploading to signed URLs (/documents/confirm).
For collection uploads, ensure you pass either collection_id or collection_name consistently.

Extraction appears “stuck”

Check is_extracting and extraction_status on the workflow response.
Use the extractions endpoints to list results and confirm pagination rather than assuming a single response will include everything.

Rate limiting / throttling

We rate-limit every API endpoint to keep the platform stable and fast for everyone building on it. When limits are exceeded, the API returns HTTP 429 Too Many Requests.

Managing rate limits

Design workflows to minimise unnecessary API calls.
Use caching and batching where appropriate to reduce the frequency of requests.
Implement idempotency to prevent duplicates during retries.
Prefer webhooks and event-driven integrations instead of aggressive polling (polling should be a last resort).
Limit request concurrency and avoid unbounded parallel processing patterns.
Ensure your application gracefully handles non-JSON error responses returned by intermediary systems.

Retry strategy (429 / intermediary throttling)

If you receive an HTTP 429 response:

Stop sending immediate follow-up requests after throttling occurs.
Retry using exponential backoff with randomized jitter (e.g. wait 1s, then 2s, then 4s, adding a small random offset each time).
Increase the delay gradually with each attempt.
Set retry limits to avoid infinite retry loops.
Avoid high-frequency polling or uncontrolled concurrent retries that may continue triggering restrictions.

Retries may help recover from temporary traffic bursts. Repeated rate-limit responses usually indicate that request patterns, concurrency levels, or polling strategies should be redesigned.

Escalation: what to send

When you escalate to your Alk account team, include:

Workflow ID and (if relevant) collection ID / document ID
Endpoint + method (e.g. GET /api/v1/workflows/{workflow_id}/…)
Timestamp (with timezone) and environment (test or live)
Request ID / correlation ID (if your system adds one)
HTTP status code and the full response body
A sanitized request (headers without secrets; body with sensitive fields redacted)
Expected vs actual behavior

If possible, attach a minimal reproducible cURL command.

Last modified on June 6, 2026

Workflows Best Practices

Error shapes

422 Validation errors

Common issues and fixes

Authentication failures (401/403)

Workflow not found (404)

Upload issues

Extraction appears “stuck”

Rate limiting / throttling

Managing rate limits

Retry strategy (429 / intermediary throttling)

Escalation: what to send

Related guides

Error shapes

422 Validation errors

Common issues and fixes

Authentication failures (401/403)

Workflow not found (404)

Upload issues

Extraction appears “stuck”

Rate limiting / throttling

Managing rate limits

Retry strategy (429 / intermediary throttling)

Escalation: what to send

Related guides