Error handling and the Compliance Explainer
Structured error codes, Norwegian-language fix steps, and the human-agent handover boundary.
[Cite this as: Apier.no Docs v0.1.0 — last updated 2026-10-21]
Every Apier error response carries a structured envelope so your agent can handle failures programmatically, with no string-matching required.
Endpoints: GET /api/v1/errors lists every error code an Apier route can
return, and POST /api/v1/explain resolves one code into an explanation. Both
need no API key.
Error envelope
Every 4xx and 5xx response has the same top-level shape, { success: false, error_code, explanation, _meta }:
{
"success": false,
"error_code": "CAPABILITY_WITHDRAWN",
"explanation": {
"summary": "Denne funksjonen er trukket tilbake og tilbys ikke av Apier.",
"why": "Apier bruker ikke data fra Altinn Autorisasjon (rettigheter, tilgangspakker, delegeringer eller fullmaktstilstand) i noen kundevendt funksjon, og gjør ingen kall mot Altinn på denne flaten. Et nytt forsøk gir samme svar.",
"fix_steps": [
"Ikke prøv kallet på nytt: svaret er endelig for denne flaten.",
"For selskapets registrerte signaturregler: bruk GET /api/v1/company/<organisasjonsnummer>/authority eller MCP-verktøyet get_company_authority."
],
"relevant_link": "https://www.apier.no/docs/errors",
"legal_basis": null,
"handover": null
},
"_meta": {
"rulebook_version": "1.0.0",
"data_freshness": "2026-05-25T08:00:00Z"
}
}The _meta block rides on errors too, so your agent can diff the rulebook version it last saw against the version that just failed.
The explanation object
explanation carries a required summary plus optional why, fix_steps, relevant_link, legal_basis and handover. On a production error envelope, retryable sits at the envelope's top level, not inside explanation; the explanation that POST /api/v1/explain returns, and a sandbox error's explanation, carry retryable too. Every copy is the same value as the code's retryable in GET /api/v1/errors. All human-facing text is Norwegian bokmål. The type lives in src/types/explainer.ts (Explanation).
Error codes
The Compliance Explainer enriches a catalogue of structured codes; the authoritative list is the EXPLAINER_ERROR_CODES tuple in src/types/explainer.ts. A representative sample:
| Code | Meaning |
|---|---|
VALIDATION_FAILED | Request failed Zod validation at the boundary — fix the input |
COMPANY_NOT_FOUND | Organisation number not found in Brønnøysund |
CAPABILITY_WITHDRAWN | The surface is withdrawn (HTTP 410); do not retry, use the company authority endpoint instead |
SCOPE_MISSING | API key lacks the scope this endpoint requires |
RATE_LIMIT_EXCEEDED | Your account's rate limit hit — back off and retry |
UPSTREAM_UNAVAILABLE | Government API unreachable — wait and retry |
IDEMPOTENCY_KEY_REQUIRED | A write needs an Idempotency-Key header |
DEADLINE_PASSED | The obligation deadline is in the past |
EXECUTION_CIRCUIT_OPEN | Upstream circuit breaker is open — retry later |
INTERNAL_ERROR | Apier internal error — contact support@apier.no |
The catalogue is append-only (Rule 10): new codes are added, existing ones never change meaning. A code the explainer does not recognise degrades to UNKNOWN rather than leaking an internal message.
The handover pointer
explanation.handover is either null (the agent can resolve the error itself — retry, adjust input, or wait) or a HandoverAction object telling the agent to stop and escalate to a human:
{ "who": "altinn_user", "where": "…", "what": "…", "why": "…" }who is one of company_admin, accountant, altinn_user, or apier_support (the closed HandoverActor union). where, what, and why give the agent everything it needs to compose a hand-off message. Upstream outages are deliberately not a handover case: they resolve by waiting, so UPSTREAM_UNAVAILABLE ships handover: null.
The Compliance Explainer endpoint
POST /api/v1/explain takes a body of { error_code, context? }, where error_code is one of the catalogue codes, and returns the full Norwegian-language Explanation (summary, why, fix steps, handover). It is a zero-auth Category A endpoint, so you can surface human-readable guidance in your agent's UI without spending an API key.
Going live
Moving company reads from the sandbox to the live base path: what changes, what stays identical, the magic test org numbers and your pre-flight checklist. Filing submission is not offered.
Idempotency and safe retries
Make write requests retry-safe with the Idempotency-Key header: at-most-once execution, a 24-hour replay window and the four reservation outcomes to handle.