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."
    ],
    "summary_en": "No active system-user delegation exists for 999999999.",
    "why_en": "The consumer has no active system-user delegation in Altinn for 999999999.",
    "fix_steps_en": [
      "Create a system user via altinn.no/systembruker and connect it to the integration.",
      "Ask a person with signing authority to approve the delegation in Altinn.",
      "Retry the request once the delegation shows as active."
    ],
    "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: its summary / why / fix_steps prose is Norwegian bokmål, carried alongside English summary_en / why_en / fix_steps_en siblings (see below). _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 Norwegian summary / why / fix_steps come with English summary_en / why_en / fix_steps_en siblings carrying the same guidance, so an English-language agent gets actionable text without translating the bokmål. The handover and legal_basis fields stay Norwegian / Lovdata-native.

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.

Machine-actionable fields

Alongside explanation, a catalogued error carries up to four top-level machine-actionable fields — siblings of error_code, not nested inside explanation. They let an agent decide whether to retry and what to change without parsing prose:

These fields are additive and optional: they are populated only for the catalogued error classes (the highest-traffic codes). A code not yet in the catalog simply omits them — there is no retryable-by-default, so their absence never implies "safe to retry". Existing consumers that read only error_code / explanation are unaffected.

Note the language contract: fix_hint is machine-facing and therefore English by default, so fix_hint and fix_hint_en carry the same English text today. This differs from the summary / summary_en pair, where summary is Norwegian bokmål and summary_en is its translation.

A transient upstream failure, for example, tells an agent to back off and retry the identical call:

{
  "success": false,
  "error_code": "UPSTREAM_UNAVAILABLE",
  "explanation": {
    "summary": "Kilden er midlertidig utilgjengelig.",
    "summary_en": "The upstream source is temporarily unavailable."
  },
  "retryable": true,
  "fix_hint": "The upstream service is unavailable or timed out — retry the identical call after a short backoff (seconds).",
  "fix_hint_en": "The upstream service is unavailable or timed out — retry the identical call after a short backoff (seconds).",
  "docs_url": "https://www.apier.no/docs/guides/error-handling",
  "_meta": {
    "rulebook_version": "2026.6.0"
  }
}

A validation failure, by contrast, carries retryable: false — resending the same body fails identically, so the agent must correct the field named in explanation.details first.

error_code catalogue

Two source files back this catalogue, and they answer different questions:

• EXPLAINER_ERROR_CODES (src/types/explainer.ts) — 40 codes that carry a full enriched explanation (summary, why, fix steps, handover), produced by the Compliance Explainer in src/lib/compliance/explainer.ts. This is the authoritative list for explanation coverage; a code outside it degrades to UNKNOWN in the explainer.
• ERROR_CATALOG (src/lib/api/error-catalog.ts) — 28 codes that additionally carry the top-level machine-actionable attributes described above (retryable, fix_hint / fix_hint_en, docs_url). This is the authoritative list for machine-actionable coverage.

The two sets overlap but neither contains the other, and a code can legitimately appear in one only. Every code from both is listed below, grouped by theme.

Auth & delegation

Validation & lookup

Scope & plan

Idempotency

Billing & credits

Money and account-ceiling errors an autonomous agent has to survive without a human in the loop. HTTP status is stated because the recovery branch usually keys on it. The full recovery walkthrough — price discovery, the 402 contract, agent-initiated top-ups — is in Agent payments. The write-limiter's RATE_LIMITED 429, which also guards the top-up and key routes, is listed under Rate limiting with its sibling.

Approval & risk

Execution & circuit

Government & upstream

Rate limiting

Two distinct limiters, two distinct codes. Both carry a Retry-After header; wait it out rather than retrying immediately.

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://www.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."
      ],
      "summary_en": "No active system-user delegation exists for 999999999.",
      "why_en": "The consumer has no active system-user delegation in Altinn for 999999999.",
      "fix_steps_en": [
        "Create a system user via altinn.no/systembruker and connect it to the integration.",
        "Ask a person with signing authority to approve the delegation in Altinn.",
        "Retry the request once the delegation shows as active."
      ],
      "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 both the Norwegian and English text wherever the template references them; omit them and the explanation falls back to a neutral noun in each language. 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.