Errors

The error body

Every non-2xx response from the public REST API (api.kausate.com/v2) has the same shape:

{
  "detail": "Company not found in Transparenzregister",
  "code": "company.not_found.transparenzregister",
  "request_id": "req_01J8Z5V4Q2X9N7B3C6D1E0F2G4"
}

On a 422 from request validation, detail is a list of per-field errors instead of a string (FastAPI's standard validation shape). code and request_id are unchanged.

Two things deliberately fall outside this shape:

• The MCP server's HTTP surface. MCP is JSON-RPC over HTTP, not REST, so its transport-level failures (a bad Accept header, an unknown path, the OAuth 401 challenge with its empty body and WWW-Authenticate header) follow the MCP and OAuth specifications rather than this body. MCP publishes the code through its own mechanisms instead — see MCP below.
• The infrastructure probes (/healthz, /readyz, /v1/health/check, /v1/health/ready), which answer with {"status": …} and no code. They are not part of the customer API and are excluded from the OpenAPI spec.

Branch on code, not on detail

Codes are hierarchical, dot-separated, and published at full leaf depth. A Transparenzregister miss is company.not_found.transparenzregister, not company.not_found. Handle a whole family at once by matching a prefix:

// Handle every "company not found" variant, however specific.
if (error.code.startsWith("company.not_found")) {
  showCompanyNotFound();
}

// Or split into segments and switch on the namespace.
const [namespace] = error.code.split(".");
if (namespace === "source") {
  scheduleRetry();
}

if error["code"].startswith("document.not_found"):
    mark_document_unavailable()

Two rules make prefix matching safe:

• Codes are many-to-one by design. Several internal conditions share one code whenever they are indistinguishable to you. A code is never more revealing than the detail it accompanies.
• Published codes are immutable. Changing or removing a code is treated as a breaking API change and is blocked by an append-only ledger in our build. New codes may be added, so always keep a default branch.

An unclassified failure emits internal.unexpected rather than omitting the field, so error.code is never undefined.

HTTP statuses

404 deliberately covers "this company has no shareholder data" and "this company has no filed financials" — routine negative results, not faults.

A capability a jurisdiction does not offer is a 400, not a 501 — the request names a combination that does not exist, and detail lists the jurisdictions that do support it. Check /v2/platform/jurisdictions for what is offered rather than discovering it from an error. A capability that is coming soon answers 403 instead. 501 is reserved for the rare case where the jurisdiction does offer the operation but a specific path is not implemented yet; neither status is worth retrying.

5xx responses are the only ones that indicate something is wrong on our side; 502 and 503 mean the registry is having problems, not Kausate.

Three further statuses are mapped but rare in day-to-day use: 413 (request.too_large), 415 (request.unsupported_media_type) and 504 (source.unavailable). Handle them through code like any other error.

Authentication: 401 vs 403

• No X-API-Key header → 401 with auth.unauthorized.
• A key that is present but not valid → 403 with auth.forbidden.
• A valid key without entitlement to that jurisdiction, capability or feature → 403 with auth.forbidden.

The last two share one code on purpose: distinguishing "that key does not exist" from "that key exists but may not do this" to an unauthenticated caller would confirm which keys are real. If your client needs to tell them apart — for example to decide between "re-read the key from the vault" and "ask us for access" — use detail for the human hint and treat any 403 as "do not retry with this key".

Credit exhaustion is a 403, not a 402. It carries the dedicated billing.credit_limit_exceeded code, so it is distinguishable from an entitlement refusal without branching on the status. Kausate emits no 402.

Statuses and codes are orthogonal

The status tells you whether to retry. The code tells you what happened. They are independent, so a code may legitimately appear at more than one status — document.extraction_failed is a 500 when we extracted the document and the data was unusable, and a 503 when the extraction run itself failed and a retry is worth making; request.invalid covers both a malformed request (400) and a well-formed one that fails validation (422).

Branch on the code for what to tell your user, and on the status class for what to do next. Never assume one implies the other.

Code vocabulary

Namespaces first — matching a namespace prefix is usually all a client needs.

The codes currently published:

Async orders and webhooks

For an async order the HTTP response is a 200 — the failure lives in the payload. Check status, then read error and code the same way:

{
  "status": "failed",
  "error": "Data source temporarily unavailable",
  "code": "source.unavailable"
}

status is one of six values. Four of them are terminal failures, and all four carry error and code — so switch on the full set, and treat anything you do not recognise as terminal rather than as "still running":

switch (order.status) {
  case "running":
    return poll();
  case "completed":
    return use(order.result);
  default:
    // failed | canceled | terminated | timedOut — all carry code + error
    return handle(order.code, order.error);
}

Webhook payloads carry the same status, error and code.

MCP

The MCP server publishes the same vocabulary, as data wherever the protocol has somewhere to put it:

A failing tool call is the one exception. MCP delivers it as a plain text block with no structured channel, so the code is emitted as a delimited marker at the very start of the message:

[code=document.temporarily_unavailable] Document is temporarily unavailable — please reach out to the Kausate support team at support@kausate.com so we can help. Quote Order ID: ord_…; Request ID: req_….

Match it anchored — /^\[code=([a-z0-9_.]+)\] / — and treat the rest of the string as display text. The marker is always first when present; it is absent only when there is no code to report.

One MCP failure precedes the marker: argument validation. If a tools/call names an argument the tool does not declare, or sends one of the wrong type, the MCP framework rejects it before our code runs and returns its own validation text with no [code=…] prefix. Treat an unmarked tool error as a malformed call — the message names the offending argument.

Why upstream failures happen

Kausate fetches directly from official government registries. Those systems are inherently unreliable: they rate-limit, they take scheduled and unscheduled maintenance windows, and some queries take 30+ seconds under load. That is why source.* codes and 429/502/503 statuses exist as a distinct family from internal.unexpected — they tell you the retry is worth making. For anything long-running, prefer asynchronous requests with webhooks (or polling by orderId): our retry logic absorbs the transient failures for you.