Copy page

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"}
• 413 Payload Too Large: returned by /documents/bulk when an uploaded file exceeds the 100 MB per-file limit

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.
• For bulk upload (/documents/bulk, /documents/confirm/bulk), a 400 usually means the manifest/items payload itself is invalid: malformed JSON, not an array, empty, an unknown filename or index, a file referenced twice or never, an ambiguous duplicate filename (reference it by index instead), validation_data that is not an object, or both collection_id and collection_name set on one item.
• Bulk upload enforces limits of 100 files and 100 items per request, and 100 MB per file (413 if exceeded). A 200 response can still contain failed items — check error on each entry in BulkUploadResponse.items.

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.
• If some documents were still converting when you called /extract, only the already-converted ones were extracted; the rest were skipped, not queued. Call /extract again once they finish converting, or set extract_when_ready on the upload call next time. See Workflows.

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.

Advanced Workflow failure points

Web Request nodes

A Web Request node calls one http or https URL from Alk's network. It can attach a bearer token, an API key (X-API-Key), or HTTP Basic (username and password). It sends that request once and reads the response. It does not follow redirects, and it does not run multi-step schemes such as NTLM.

When the node fails, the run shows one of two shapes:

• A refusal, when the URL is rejected before anything is sent.
• METHOD host failed (ErrorName) or METHOD host returned STATUS, when a request was attempted. ErrorName is the transport failure. STATUS is the HTTP status when the server answered.

The node's timeout defaults to 30 seconds and is capped at 60.

Inspect the route first

Before changing the node, ask the server what it expects. Run this from a machine that can reach the host:

Code
curl -k -I -u 'username:password' 'https://host:port/path'

• -k still prints headers when the certificate is private or self-signed.
• -I asks for headers only.
• -u sends the username and password as HTTP Basic, the same shape as Username & Password on the node.

Read WWW-Authenticate on the response:

WWW-Authenticate	What to do
Basic	Username & Password matches this server. A 401 means the username or password was rejected.
Bearer	Use Bearer Token. A 401 means the token was rejected.
NTLM or Negotiate	This server wants a Windows challenge handshake. The node cannot complete it. The run returns 401.
More than one scheme	Any listed scheme the node supports (Basic or Bearer) can be used. NTLM alone cannot.
Header absent, and the status is 200	The route accepted Basic, or it does not require authentication.

If HEAD is rejected (405), drop -I and still read the headers:

Code
curl -k -D - -u 'username:password' -o /dev/null 'https://host:port/path'

The node verifies TLS certificates. A URL that only responds to curl -k can still fail in the node with ConnectError until the server's certificate is publicly trusted.

401 Unauthorized

401 means the server was reached and refused the credentials or the auth scheme. The run shows METHOD host returned 401.

Check WWW-Authenticate with the curl command above:

• Basic. The username or password does not match what the server expects. {{field}} tokens in the username and password are sent as written; they are not filled in from earlier steps.
• Bearer. The token is missing, expired, or wrong. Select Bearer Token on the node.
• NTLM or Negotiate. The node sent a single Authorization: Basic … header (or a bearer token). NTLM needs a challenge and a second request, which the node does not send, so the server answers 401 even when the username and password are correct. On-premises Windows services, including Business Central web services, commonly advertise NTLM. Point the node at a route that accepts Basic or Bearer, or put a proxy in front of the service that accepts one of those and speaks NTLM upstream.
• No WWW-Authenticate header. The service rejected the call without naming a scheme. Confirm the path and method with the service owner. SOAP endpoints usually expect POST.

A 403 is the same reachability with a permission failure: the credentials were recognized and the account is not allowed to call that route.

Internal endpoints

The node calls the public internet. A host that only exists on a private network fails in one of two ways.

Private address. Loopback, link-local, and private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) are refused before a connection is opened:

Requests to <host> are blocked because it resolves to a private or reserved address.

If curl to the same host and port hangs from outside the private network, this is a reachability failure, not authentication.

Other connection failures

The name in parentheses is what the run shows.

Error	Meaning
ConnectTimeout	DNS worked, and the TCP connection did not finish before the timeout. See Internal endpoints when the service is not public. Otherwise the port is filtered or nothing is listening.
ConnectError	The connection failed after the address was known, most often TLS: an untrusted, expired, or hostname-mismatched certificate. Compare with curl without -k.
ReadTimeout, WriteTimeout, ReadError, WriteError	The connection opened, then stalled or dropped while the body was sent or read. Raise the node's timeout (up to 60 seconds) or have the service answer faster.
HostResolutionError	The hostname did not resolve on the public DNS the node uses. Check the host for a typo. A name that resolves only on an internal DNS server fails here.

Other HTTP statuses

The server answered. The run shows METHOD host returned STATUS when On error is Fail.

Status	Usual cause
301, 302, 303, 307, 308	Redirect. The node does not follow it. Call the final URL directly.
404	Path, company, or codeunit name does not match the service.
405	Method is not allowed. SOAP endpoints usually expect POST.
5xx	The service failed. The status and body are the service's own error.

A body larger than 1 MB is cut off at that size.

URL and graph setup

These fail the run before a request is sent:

Message	Fix
Web Request needs a URL.	Set the URL.
the URL must start with http:// or https://	Use http or https.
the scheme and host must be written out in full	Write the scheme and host literally. {{values}} are allowed in the path, query, headers, and body.
The Web Request URL has no host.	Include a hostname.
Put credentials in the auth settings, not in the URL.	https://user:password@host/... is refused. Put the username and password in the node's authentication settings.
'…' sends one request per document, so connect it to the approval stage's approved (or rejected) path.	A per-document request downstream of an approval must leave the approved or rejected handle, so each document already has a decision.

Related guides

• Integration Journey
• Best Practices
• Workflows