Troubleshooting auth errors and the structured error envelope
Every Apier 4xx/5xx response carries the same structured envelope — { success: false, error_code, explanation, _meta } — so agents handle failures programmatically without string-matching. A 401 means the request never authenticated: a missing, malformed, revoked, or unknown key; authorization failures (missing delegation, missing scope) surface as their own codes.
Jurisdiction: Norway · Verified against Apier as of 2026-05-25
The error envelope
explanation carries a required summary plus optional why, fix_steps, relevant_link, legal_basis, and handover — all human-facing text in Norwegian bokmål. The _meta trust block rides on errors too, so an agent can diff the rulebook version it last saw against the version that just failed. The code catalogue is append-only: new codes are added, existing ones never change meaning, and an unrecognised code degrades to UNKNOWN rather than leaking an internal message.
Reading a 401
A 401 is an authentication failure: no key, an invalid or revoked key, or an Authorization header that never survived the HTTP layer (malformed Bearer values with whitespace or paste artifacts are stripped per RFC 7230 and surface as AUTH_MISSING). It is distinct from authorization failures on a valid key: SCOPE_MISSING (key lacks the endpoint's scope) and AUTH_NO_DELEGATION (the target company never delegated access) tell an agent something different from 'your key is wrong'.
Self-service vs handover
explanation.handover is either null — the agent can resolve the error itself by retrying, adjusting input, or waiting — or a HandoverAction object telling the agent to stop and escalate to a human. who is one of company_admin, accountant, altinn_user, or apier_support; where, what, and why give the agent everything needed to compose the 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 { error_code, context? } and returns the full Norwegian-language explanation (summary, why, fix steps, handover). It is a zero-auth Category A endpoint, so an agent can surface human-readable guidance in its UI without spending an API key — useful precisely when the API key itself is the thing that is failing.
Use cases
- Branch agent behaviour on error_code instead of brittle message string-matching
- Decide automatically whether to retry, fix input, wait, or hand over to a human
- Render human-readable Norwegian guidance for any error code without authentication
Requirements
- None for the Compliance Explainer itself (zero-auth)
- The error_code from the failing response, and ideally its X-Correlation-ID for support escalation
Authentication
Method: none
The explainer endpoint is Category A zero-auth by design, so it keeps working when the caller's key does not.
Common errors
AUTH_MISSING
No usable Authorization header reached the API (absent or stripped as malformed at the HTTP layer).
Fix: Send Authorization: Bearer <key> as one clean line; check the key file for line breaks or stray whitespace.
AUTH_NO_DELEGATION
The organisation has not delegated system-user access, so delegated data cannot be read.
Fix: Escalate: the company must create a system user in Altinn and delegate access (handover actor: altinn_user).
SCOPE_MISSING
The API key lacks the scope this endpoint requires.
Fix: Mint or update a key with the required scope, then retry.
RATE_LIMIT_EXCEEDED
The tier rate limit was hit.
Fix: Back off and retry after the Retry-After delay.
UPSTREAM_UNAVAILABLE
A government API is unreachable — not a handover case.
Fix: Wait and retry with backoff; the condition resolves on its own.
Related topics
Related APIs
Capability ids — resolve each against the machine-readable manifest at /api/v1/capabilities for the endpoint, auth mode, and tier.
- tools.explain
- admin.keys.list
Related MCP tools
Registered tools on the Apier MCP server.
- explain_compliance_error