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 envelopeCopy Anchor Link

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

{
  "success": false,
  "error_code": "SCOPE_RESERVED",
  "explanation": {
    "summary": "Endepunktet krever et reservert scope som ikke kan tildeles.",
    "why": "Scopene write:, act: og delegate: er reservert og utstedes ikke ennå. Ingen nøkkel kan bære dem, så et nytt forsøk med en annen nøkkel feiler likt.",
    "fix_steps": [
      "Ikke gjenta kallet: ingen nøkkel kan få dette scopet i dag.",
      "Bruk et lesende alternativ for å komme videre uten bindende skriving.",
      "Kontakt Apier hvis du trenger denne flaten; åpningen krever en beslutning hos Apier, ikke en endring av nøkkelen din."
    ],
    "summary_en": "The endpoint requires a reserved scope that cannot be granted.",
    "why_en": "The write:, act: and delegate: scopes are reserved and not issued yet. No key can carry them, so retrying with a different key fails identically.",
    "fix_steps_en": [
      "Do not retry the call: no key can hold this scope today.",
      "Use a read-only alternative to make progress without a binding write.",
      "Contact Apier if you need this surface; opening it is a decision at Apier, not a change to your key."
    ],
    "relevant_link": "https://www.apier.no/docs/authentication",
    "legal_basis": null,
    "handover": {
      "who": "apier_support",
      "where": "https://www.apier.no/support",
      "what": "Be Apier om tilgang til den reserverte flaten, og beskriv hvilken handling integrasjonen trenger.",
      "why": "Reserverte scope kan ikke utstedes til en nøkkel; flaten åpnes ved en beslutning hos Apier, og ingen endring agenten gjør vil endre svaret."
    }
  },
  "_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 objectCopy Anchor Link

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 objectCopy Anchor Link

When an agent reaches a boundary it cannot cross on its own (a reserved scope no key can hold, a human approval it cannot give itself, 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 fieldsCopy Anchor Link

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 catalogueCopy Anchor Link

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, retryable) that every one of these codes also carries, see Get a live explanation below.

Withdrawn surfaces (2026-10-21)Copy Anchor Link

Altinn Servicedesk answered in writing on 2026-10-21, after legal review, that Altinn Autorisasjon data may not be the basis of a commercial service. The fullmakt, acting-capacity, delegation-status, filing-history and filing action routes (/api/v1/fullmakt/*, /api/v1/altinn/list-acting-capacity, /api/v1/auth/permissions/{org}, /api/v1/auth/system-user/delegate, /api/v1/company/{org}/filing-history, /api/v1/actions/*) are withdrawn: every call answers HTTP 410 with error_code: "CAPABILITY_WITHDRAWN" (retryable: false), before authentication and without any upstream call. The legacy codes those routes used to emit (AUTH_NO_DELEGATION, AUTH_MISSING_DELEGATION, ALTINN_DELEGATION_MISSING, DELEGATION_*, FULLMAKT_*, MASKINPORTEN_*, APPROVAL_TOKEN_*) stay in the registry below for compatibility only; nothing on the live surface asks you to request a delegation or set up a system user. For the register's coded signing rules for a company, call /api/v1/company/{org}/authority (signaturrett and prokura from Brønnøysund).

Get a live explanationCopy Anchor Link

Every code in the registry above carries a Compliance Explainer template in English and bokmål (EXPLAINER_ERROR_CODES in src/types/explainer.ts, pinned to the whole registry by a coverage test; the full list is published in the Explanation schema's error_code enum in openapi.json), so any of them 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": "CAPABILITY_WITHDRAWN" }'

The response wraps the explanation in the standard success envelope:

{
  "success": true,
  "data": {
    "explanation": {
      "error_code": "CAPABILITY_WITHDRAWN",
      "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 (signaturrett og prokura fra Brønnøysund) eller MCP-verktøyet get_company_authority.",
        "Se /docs/changelog for hvilke flater som er trukket tilbake og hva som erstatter dem."
      ],
      "summary_en": "This capability is withdrawn and is not offered by Apier.",
      "why_en": "Apier does not use Altinn Autorisasjon data (rights, access packages, delegations or fullmakt state) in any customer-facing feature, and makes no Altinn call on this surface. A retry returns the same answer.",
      "fix_steps_en": [
        "Do not retry the call: the answer is final for this surface.",
        "For the register's coded signing rules for a Norwegian company: use GET /api/v1/company/<org_number>/authority (signaturrett and prokura from Brønnøysund) or the MCP tool get_company_authority.",
        "See /docs/changelog for which surfaces are withdrawn and what replaces them."
      ],
      "relevant_link": "https://www.apier.no/docs/errors",
      "legal_basis": null,
      "handover": null,
      "retryable": false
    }
  },
  "_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 deeperCopy Anchor Link

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.