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/hjelp/systemtilgang 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/hjelp/systemtilgang 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://info.altinn.no/hjelp/systemtilgang/om-systemtilgang/",
    "legal_basis": null,
    "handover": {
      "who": "company_admin",
      "where": "https://info.altinn.no/hjelp/systemtilgang/om-systemtilgang/",
      "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, every error carries six top-level machine-actionable fields, siblings of error_code rather than nested inside explanation. They let an agent decide whether to retry and what to change without parsing prose:

These fields are additive (Rule 10): existing consumers that read only error_code / explanation are unaffected. Since the error registry landed, they are populated for every code the API can emit; the catalogue below is complete by construction, and a code that somehow reached the envelope builder without an entry is collapsed to INTERNAL_ERROR rather than leaking an undocumented string. There is still no retryable-by-default: never infer "safe to retry" from anything but an explicit retryable: true.

The whole registry is also served as JSON, keylessly, at GET /api/v1/errors: { schema_version, count, categories, retryable_contract, errors: [{ code, category, retryable, fix_hint_en, fix_hint_nb, docs_url }], docs_url, explain_endpoint } (retryable_contract restates what retryable means; docs_url points here; explain_endpoint is the path of POST /api/v1/explain), with errors sorted by code, so an agent can load its recovery policy once at startup instead of discovering the vocabulary one failure at a time.

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). See also https://www.apier.no/docs/guides/error-handling.",
  "fix_hint_en": "The upstream service is unavailable or timed out — retry the identical call after a short backoff (seconds). See also https://www.apier.no/docs/guides/error-handling.",
  "fix_hint_nb": "Oppstrømstjenesten er utilgjengelig eller tidsavbrutt — gjenta det identiske kallet etter en kort pause (sekunder). Se også https://www.apier.no/docs/guides/error-handling.",
  "docs_url": "https://www.apier.no/docs/errors#upstream_unavailable",
  "category": "upstream",
  "_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

Every code below is rendered at build time from the error catalog (ERROR_CATALOG in src/lib/api/error-catalog.ts), the same table errorResponse stamps onto a live envelope and the keyless GET /api/v1/errors registry serves. There is no hand-maintained list: a code is documented here if and only if it can reach the wire, and the machine registry, this page and the ErrorCode enum in openapi.json are gated to stay the same set.

Each entry shows the code's category, its retryable verdict, the English and bokmål one-line remediation (fix_hint_en / fix_hint_nb) and its docs_url. Every code has its own anchor on this page (#<code in lower case>) and every row's docs_url points at it; where a fuller recovery loop lives in a guide (error-handling, idempotency, agent-payments, authentication), the fix hint ends with a "See also" link to it. Follow the served value rather than deriving it from the code. The bokmål hints are first-pass translations awaiting native-speaker review.

For the fuller explanation object (summary, why, ordered fix steps, handover) that a subset of these codes also carries, see Get a live explanation below.

Get a live explanation

The codes that carry a Compliance Explainer template (EXPLAINER_ERROR_CODES in src/types/explainer.ts, a subset of the registry above; the full list is published in the Explanation schema's error_code enum in openapi.json) 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/hjelp/systemtilgang 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/hjelp/systemtilgang 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://info.altinn.no/hjelp/systemtilgang/om-systemtilgang/",
      "legal_basis": null,
      "handover": {
        "who": "company_admin",
        "where": "https://info.altinn.no/hjelp/systemtilgang/om-systemtilgang/",
        "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.