Error reference

Every Apier API error returns the same structured envelope, so your agent can branch on a machine-readable error_code instead of string-matching prose. This page is the canonical reference for that envelope, the explanation object it carries, and every error_code the API can emit.

The error envelope

Every 4xx and 5xx response from /api/v1/* has the same top-level shape — { success: false, error_code, explanation, _meta }:

{
  "success": false,
  "error_code": "AUTH_NO_DELEGATION",
  "explanation": {
    "summary": "Ingen aktiv systembruker-delegering finnes for 999999999.",
    "why": "Konsumenten har ingen aktiv systembruker-delegering hos Altinn for 999999999.",
    "fix_steps": [
      "Opprett en systembruker via altinn.no/systembruker og knytt den til integrasjonen.",
      "Be en signaturberettiget godkjenne delegeringen i Altinn.",
      "Gjenta forespørselen når delegeringen vises som aktiv."
    ],
    "relevant_link": "https://altinn.no/systembruker",
    "legal_basis": null,
    "handover": {
      "who": "company_admin",
      "where": "https://altinn.no/systembruker",
      "what": "Opprette systembruker og godkjenne delegering for 999999999.",
      "why": "Uten delegering har systembrukeren ingen rettigheter på vegne av organisasjonen."
    }
  },
  "_meta": {
    "rulebook_version": "2026.6.0",
    "data_freshness": "2026-06-23T08:00:00Z"
  }
}

success is always false on an error. error_code is a stable machine string from the catalogue below. explanation is human-and-agent readable, and all of its prose is Norwegian bokmål. _meta rides on errors too, so your agent can diff the rulebook_version it last saw against the one that just failed. Every value above is synthetic — 999999999 is the documentation fixture organisation number.

The explanation object

explanation always carries a summary; every other field is optional and present only when it applies. The type is ApiErrorExplanation in src/types/api.ts.

The handover object

When an agent reaches a boundary it cannot cross on its own — an Altinn role that isn't delegated, a Maskinporten scope that isn't granted, or an error that needs Apier triage — explanation.handover names who must step in. It is absent for errors the agent can resolve itself by retrying, adjusting input, or waiting.

error_code catalogue

The authoritative list is the EXPLAINER_ERROR_CODES tuple in src/types/explainer.ts — 38 codes, grouped below by theme. Each code's enriched explanation (summary, fix steps, handover) is produced by the Compliance Explainer in src/lib/compliance/explainer.ts.

Auth & delegation

Validation & lookup

Scope & plan

Idempotency

Approval & risk

Execution & circuit

Government & upstream

Rate limiting

Sandbox

General & fallback

Get a live explanation

Every code above can be expanded into a full explanation object on demand. POST /api/v1/explain is a zero-auth endpoint (no API key needed) that takes an error_code plus an optional context and returns the canonical explanation — the same object the API attaches to a real error. It makes no upstream calls and stores no data.

curl -X POST https://apier.no/api/v1/explain \
  -H "Content-Type: application/json" \
  -d '{ "error_code": "AUTH_NO_DELEGATION", "context": { "org_number": "999999999" } }'

The response wraps the explanation in the standard success envelope:

{
  "success": true,
  "data": {
    "explanation": {
      "error_code": "AUTH_NO_DELEGATION",
      "summary": "Ingen aktiv systembruker-delegering finnes for 999999999.",
      "why": "Konsumenten har ingen aktiv systembruker-delegering hos Altinn for 999999999.",
      "fix_steps": [
        "Opprett en systembruker via altinn.no/systembruker og knytt den til integrasjonen.",
        "Be en signaturberettiget godkjenne delegeringen i Altinn.",
        "Gjenta forespørselen når delegeringen vises som aktiv."
      ],
      "relevant_link": "https://altinn.no/systembruker",
      "legal_basis": null,
      "handover": {
        "who": "company_admin",
        "where": "https://altinn.no/systembruker",
        "what": "Opprette systembruker og godkjenne delegering for 999999999.",
        "why": "Uten delegering har systembrukeren ingen rettigheter på vegne av organisasjonen."
      }
    }
  },
  "_meta": {
    "rulebook_version": "2026.6.0"
  }
}

The context fields (org_number, scope, role, field, upstream_system) are interpolated into the Norwegian text wherever the template references them; omit them and the explanation falls back to a neutral Norwegian noun. The standard trust _meta block rides on the response alongside rulebook_version.

Going deeper

This page is the canonical index. For a walkthrough of handling these errors in agent code — retry strategy, the human-handover boundary, and worked examples — see Error handling and the Compliance Explainer.