API Errors

Purpose

API clients should treat response status, hasErrors, and validation messages as part of the same error-handling model.

Response Handling

1. Read the HTTP status code.
2. Parse the response body as JSON.
3. Check hasErrors when present.
4. Read data, meta, and error messages according to the endpoint.
5. Log enough context for support without exposing secrets or full document content.

cuidado

Some Cogneris backend responses are returned with Content-Type: text/plain while the body contains JSON. API clients should parse the response body as JSON even when the content type is not application/json.

Common Conditions

Condition	Likely Cause	Action
401 Unauthorized	Authorization header missing or malformed, or the key is unknown, revoked or expired. Both xtkt_live_ and xtkt_test_ keys are accepted when valid and active.	Send Authorization: Bearer <key> with an active key of your tenant's region
403 Forbidden with code environment.sandbox_route_unavailable	A sandbox key (xtkt_test_) on a route sandbox does not cover — every synchronous /Document/* endpoint, for example	Use a production key (xtkt_live_), or the asynchronous job flow
403 Forbidden (other codes)	The key lacks a required scope, or the tenant has no active subscription for the operation	Check the key's access and your plan
413 / 415	File over 10 MB (500 MB on /Document/split) or extension not supported	Send a supported file within the limit
429 Too Many Requests	Over 50 requests per key in the current 1-minute window, or the document quota is exhausted	Wait for Retry-After, then retry
5xx	Document, provider, or service failure	Retry with known-good input; quote the correlationId to support

Errors raised before the request is processed (400, 401, 429, 500) are application/problem+json documents with a stable code, a retryable flag and a correlationId. Branch on code, and retry only when retryable is true.

Related Docs

• API Authentication
• API Examples