# Fejl og statuskoder

Alle fejl har samme form — en tekst, en stabil fejltype og kaldets request-id — og en HTTP-status, der fortæller, om du skal rette kaldet, opgradere, vente eller prøve igen.

## Fejlformatet

En fejl er altid et JSON-objekt. `error` beskriver fejlen på engelsk, præcis som før; ved siden af står felter, du kan bygge logik på:

```json
{
  "error": "this API key is not scoped for 'cvr'",
  "type": "key_scope",
  "code": "key_scope_missing",
  "message": "API-nøglen har ikke adgang til dette område.",
  "request_id": "6f1c2b0e-3a4d-4c1f-9e2b-8d7a5c4b3a21",
  "doc_url": "https://grundfast.dk/docs/fejl#key_scope"
}
```

- **`type`** er fejltypen — en af typerne i [listen nedenfor](#fejltyper) og i [`GET /v1/errors`](https://grundfast.dk/docs/api/fejlkatalog). Forgren på den eller på HTTP-statussen, ikke på teksten.
- **`code`** er den konkrete årsag, hvor vi kender den, fx `api_key_missing` frem for `api_key_invalid`. Ellers er den lig med `type`.
- **`message`** er beskeden til et menneske, på dansk som standard og på engelsk, når kaldet sender `Accept-Language: en`. Hvor vi kender årsagen, står den her — fx at `lat` og `lon` ser ud til at være byttet om — ellers en kort tekst for fejltypen. Svaret bærer `Content-Language`.
- **`param`** (kan forekomme) er den parameter, der er galt med, fx `lon` eller `bfe`.
- **`hint`** (kan forekomme) siger, hvad du skal sende i stedet, når vi kan læse det ud af kaldet: `lng` i stedet for `lon`, byttede koordinater, decimalkomma, et BFE-nummer skrevet med punktummer, eller nøglen sendt i `X-API-Key` i stedet for `Authorization: Bearer`.
- **`request_id`** er det samme som `X-Request-Id`-headeren. Angiv det, hvis du kontakter support om et bestemt kald.
- **`doc_url`** peger på fejltypen på denne side.

Teksten i `error` kan blive præciseret over tid; `type` og `code` er stabile. Klienter, der kun læser `error`, virker uændret.

## Statuskoder

Tabellen er dannet direkte fra API’ets eget fejlkatalog — den samme liste, som API’et er kontrolleret imod, så en ny fejlstatus ikke kan tages i brug uden at stå her. Kataloget kan også hentes maskinlæsbart og uden nøgle fra [`GET /v1/errors`](https://grundfast.dk/docs/api/fejlkatalog), med en stabil `type` pr. fejltype.

| Status | Betydning i Grundfast | Prøv igen? |
| --- | --- | --- |
| 400 | Ugyldig forespørgsel: forkert BFE- eller UUID-format, en manglende eller for kort parameter, et koordinat uden for Danmark, en ugyldig `asOf`, `srid`, `cirkel` eller `polygon`, eller et body, der ikke passer til skemaet. `message` siger på dansk, hvad der er galt, og `param` og `hint` peger på parameteren og rettelsen, hvor vi kan se den (fx `lng` i stedet for `lon`, byttede koordinater, decimalkomma eller et BFE-nummer med punktummer). Et 400-svar tæller ikke i kvoten. | Nej — ret kaldet. |
| 401 | Nøglen mangler, er ugyldig, udløbet eller tilbagekaldt. `code` skelner: `api_key_missing` (ingen nøgle sendt), `api_key_invalid` (nøglen kendes ikke) og `api_key_wrong_header` (nøglen blev sendt i fx `X-API-Key`, som ikke læses — send `Authorization: Bearer <nøgle>`). Svaret bærer en `WWW-Authenticate`-header og et `hint`, der beskriver formatet. | Nej — ret kaldet. |
| 402 | Funktionen eller størrelsen er ikke med i din plan. Batch og webhooks kræver Pro; eksport og historik (`asOf` og `/historik`) kræver Scale. Det samme svar får en batch med flere id’er, end din plan tager pr. kald, og et job med flere rækker, end din plan tager pr. job. Beskeden nævner grænsen og den plan, der skal til — eller at listen kan sendes som et job. Planen har ikke flere pladser: brugere og ventende invitationer fylder tilsammen det antal, planen giver. Fjern en bruger eller invitation, eller opgrader. | Nej — ret kaldet. |
| 403 | Kontoen er suspenderet, eller nøglen er en administrationsnøgle, der ikke gælder for data-endpoints. Nøglen er begrænset til bestemte områder (scopes), og endpointet ligger uden for dem. Svaret nævner det scope, der mangler. Udvid nøglens scopes i dashboardet, eller brug en anden nøgle. Din rolle på kontoen (fx Læseadgang eller Økonomi) tillader ikke handlingen. Bed en ejer om en anden rolle. Et kald med cookie-session fra et andet site til et konto-endpoint (login, nøgler, betaling) afvises. Gælder ikke kald med API-nøgle. En offentlig nøgle (`gf_pub_`) blev brugt fra et site, der ikke står på nøglens liste over tilladte origins — eller uden `Origin`- og `Referer`-header. Tilføj domænet til nøglen under Nøgler i dashboardet. Svaret er åbnet for CORS, så fejlen kan læses i browserens konsol. En offentlig nøgle (`gf_pub_`) åbner kun adresse-autocomplete og opslag (GET på søgning, autocomplete, adresseopslag, datavask og postnumre). Alt andet — registre, batch, eksport, konto — kræver en hemmelig nøgle fra en server. | Nej — ret kaldet. |
| 404 | Ressourcen findes ikke: ukendt BFE, UUID, CVR-nummer, kode eller sti. | Nej — ret kaldet. |
| 405 | Stien findes, men ikke med den HTTP-metode, du brugte (fx `POST` på et opslag, der kun tager `GET`). `Allow`-headeren og feltet `allow` siger, hvilke metoder stien tager. | Nej — ret kaldet. |
| 409 | Ressourcen er ikke i en tilstand, der tillader kaldet — typisk en eksport, der ikke er færdig endnu, når du henter filen, et job, der ikke kan sættes på pause, genoptages eller stoppes fra sin nuværende status, rækker sendt til et job, der ikke længere er en kladde, et sjette åbent job, når du allerede har fem, eller en webhook-genlevering af en hændelse, der allerede står i kø, eller til et endpoint, der er sat på pause. | Ja, når forudsætningen er opfyldt. |
| 410 | Et jobs rækker er slettet: resultat- og fejlfilen gemmes i en begrænset periode efter, at jobbet er færdigt (30 dage som standard). Jobbet står stadig på listen med `resultsAvailable: false`. Kør listen igen som et nyt job, hvis du har brug for den. | Nej — ret kaldet. |
| 413 | Request-body over 1 MB — eller over 10 MB for en upload til `/v1/jobs`. Del kaldet op; en lang liste uploades i dele med `POST /v1/jobs/{id}/rows`. | Nej — ret kaldet. |
| 415 | Et konto-endpoint fik et body, der ikke er `application/json`. Send `Content-Type: application/json`. | Nej — ret kaldet. |
| 422 | Jordstykket kunne findes, men bærer ingen ejerlavskode og intet matrikelnummer, så kortlægningen kan ikke slås op på matriklen. Slå op på koordinatet i stedet. Oprettelse af en konto eller skift af e-mail med en engangs-e-mailadresse (fx mailinator eller yopmail). Brug en adresse, du beholder — kontoens bekræftelse, kvitteringer og driftsbeskeder går dertil. | Nej — ret kaldet. |
| 429 | Burst-grænsen pr. minut for din plan er nået — eller, for en offentlig nøgle, grænsen pr. IP-adresse pr. minut. Også når kontoen allerede har 5 ændringsstrømme (`/v1/aendringer/stream`) åbne — luk én, før du åbner en ny — eller serveren ikke har plads til flere strømme lige nu, og når grænsen pr. time for at sende webhook-leveringer igen er nået (120 enkelte og 10 "send alle fejlede" i timen). `Retry-After` siger, hvornår du kan prøve igen; body’et har grænsen (`limit`, `window_s`) og ventetiden (`retry_after_s`). Månedens kvote er brugt (eller sandbox-loftet for en testnøgle). Svaret bærer `X-Quota-*`-headere, og `Retry-After` peger på næste måned — prøv ikke igen automatisk. Body’et har kvoten (`limit`) og et link til at opgradere (`upgrade_url`). For mange forsøg med ugyldige nøgler fra samme IP-adresse. Ret nøglen og vent det antal sekunder, `Retry-After` angiver. | `rate_limited`: Ja, efter `Retry-After`. `quota_exceeded`: Nej — ret kaldet. `auth_throttled`: Ja, efter `Retry-After`. |
| 500 | En uventet fejl hos os. Den er logget med kaldets `X-Request-Id`; angiv det, hvis du kontakter support. | Ja, med backoff. |
| 502 | Kilden (fx Datafordeler) svarede med fejl, efter vi har prøvet igen, og der var ingen brugbar cachet kopi. | Ja, med backoff. |
| 503 | Kilden er ikke tilgængelig i øjeblikket, endpointet er ikke sat op i dette miljø (fx adresseindekset eller rumlige filtre), eller rate-limiteren er midlertidigt utilgængelig. Energimærke: ejendommen er ikke dækket endnu. Det er ikke det samme som "intet energimærke" — det ville være en 404. | Ja, med backoff. |
| 504 | Svaret tog længere end tidsgrænsen på ca. 20 sekunder. Arbejdet fortsætter i baggrunden, så et nyt kald er ofte hurtigt. | Ja, med backoff. |

## Fejltyper

Hver fejltype har sit eget afsnit, som `doc_url` i fejlsvaret peger direkte på.

### 400 · invalid_request

Ugyldig forespørgsel: forkert BFE- eller UUID-format, en manglende eller for kort parameter, et koordinat uden for Danmark, en ugyldig `asOf`, `srid`, `cirkel` eller `polygon`, eller et body, der ikke passer til skemaet. `message` siger på dansk, hvad der er galt, og `param` og `hint` peger på parameteren og rettelsen, hvor vi kan se den (fx `lng` i stedet for `lon`, byttede koordinater, decimalkomma eller et BFE-nummer med punktummer). Et 400-svar tæller ikke i kvoten. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `invalid BFE number`.

### 401 · invalid_api_key

Nøglen mangler, er ugyldig, udløbet eller tilbagekaldt. `code` skelner: `api_key_missing` (ingen nøgle sendt), `api_key_invalid` (nøglen kendes ikke) og `api_key_wrong_header` (nøglen blev sendt i fx `X-API-Key`, som ikke læses — send `Authorization: Bearer <nøgle>`). Svaret bærer en `WWW-Authenticate`-header og et `hint`, der beskriver formatet. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `invalid API key`.

### 402 · plan_required

Funktionen eller størrelsen er ikke med i din plan. Batch og webhooks kræver Pro; eksport og historik (`asOf` og `/historik`) kræver Scale. Det samme svar får en batch med flere id’er, end din plan tager pr. kald, og et job med flere rækker, end din plan tager pr. job. Beskeden nævner grænsen og den plan, der skal til — eller at listen kan sendes som et job. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `this feature requires the Pro plan or higher; …`.

### 402 · seat_limit

Planen har ikke flere pladser: brugere og ventende invitationer fylder tilsammen det antal, planen giver. Fjern en bruger eller invitation, eller opgrader. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `your plan includes 3 seats and all are taken; …`.

### 403 · forbidden

Kontoen er suspenderet, eller nøglen er en administrationsnøgle, der ikke gælder for data-endpoints. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `account suspended — contact support`.

### 403 · key_scope

Nøglen er begrænset til bestemte områder (scopes), og endpointet ligger uden for dem. Svaret nævner det scope, der mangler. Udvid nøglens scopes i dashboardet, eller brug en anden nøgle. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `this API key is not scoped for 'bbr'`.

### 403 · team_role

Din rolle på kontoen (fx Læseadgang eller Økonomi) tillader ikke handlingen. Bed en ejer om en anden rolle. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `your team role 'read_only' does not allow this action`.

### 403 · cross_site_refused

Et kald med cookie-session fra et andet site til et konto-endpoint (login, nøgler, betaling) afvises. Gælder ikke kald med API-nøgle. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `cross-site request rejected`.

### 403 · origin_not_allowed

En offentlig nøgle (`gf_pub_`) blev brugt fra et site, der ikke står på nøglens liste over tilladte origins — eller uden `Origin`- og `Referer`-header. Tilføj domænet til nøglen under Nøgler i dashboardet. Svaret er åbnet for CORS, så fejlen kan læses i browserens konsol. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `origin https://example.dk is not allowed for this public key — …`.

### 403 · public_key_scope

En offentlig nøgle (`gf_pub_`) åbner kun adresse-autocomplete og opslag (GET på søgning, autocomplete, adresseopslag, datavask og postnumre). Alt andet — registre, batch, eksport, konto — kræver en hemmelig nøgle fra en server. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `public keys only open the address autocomplete endpoints — use a secret key`.

### 404 · not_found

Ressourcen findes ikke: ukendt BFE, UUID, CVR-nummer, kode eller sti. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `property not found`.

### 405 · method_not_allowed

Stien findes, men ikke med den HTTP-metode, du brugte (fx `POST` på et opslag, der kun tager `GET`). `Allow`-headeren og feltet `allow` siger, hvilke metoder stien tager. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `method not allowed`.

### 409 · conflict

Ressourcen er ikke i en tilstand, der tillader kaldet — typisk en eksport, der ikke er færdig endnu, når du henter filen, et job, der ikke kan sættes på pause, genoptages eller stoppes fra sin nuværende status, rækker sendt til et job, der ikke længere er en kladde, et sjette åbent job, når du allerede har fem, eller en webhook-genlevering af en hændelse, der allerede står i kø, eller til et endpoint, der er sat på pause. Prøv igen: Ja, når forudsætningen er opfyldt. Eksempel på `error`: `export not ready (status: processing)`.

### 410 · job_rows_deleted

Et jobs rækker er slettet: resultat- og fejlfilen gemmes i en begrænset periode efter, at jobbet er færdigt (30 dage som standard). Jobbet står stadig på listen med `resultsAvailable: false`. Kør listen igen som et nyt job, hvis du har brug for den. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `the rows of this job have been deleted (results are kept for a limited time)`.

### 413 · payload_too_large

Request-body over 1 MB — eller over 10 MB for en upload til `/v1/jobs`. Del kaldet op; en lang liste uploades i dele med `POST /v1/jobs/{id}/rows`. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `Payload too large`.

### 415 · unsupported_media_type

Et konto-endpoint fik et body, der ikke er `application/json`. Send `Content-Type: application/json`. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `expected application/json`.

### 422 · unprocessable_parcel

Jordstykket kunne findes, men bærer ingen ejerlavskode og intet matrikelnummer, så kortlægningen kan ikke slås op på matriklen. Slå op på koordinatet i stedet. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `jordstykke carries no cadastral key`.

### 422 · disposable_email

Oprettelse af en konto eller skift af e-mail med en engangs-e-mailadresse (fx mailinator eller yopmail). Brug en adresse, du beholder — kontoens bekræftelse, kvitteringer og driftsbeskeder går dertil. Prøv igen: Nej — ret kaldet. Eksempel på `error`: `disposable email addresses are not accepted; use an address you will keep`.

### 429 · rate_limited

Burst-grænsen pr. minut for din plan er nået — eller, for en offentlig nøgle, grænsen pr. IP-adresse pr. minut. Også når kontoen allerede har 5 ændringsstrømme (`/v1/aendringer/stream`) åbne — luk én, før du åbner en ny — eller serveren ikke har plads til flere strømme lige nu, og når grænsen pr. time for at sende webhook-leveringer igen er nået (120 enkelte og 10 "send alle fejlede" i timen). `Retry-After` siger, hvornår du kan prøve igen; body’et har grænsen (`limit`, `window_s`) og ventetiden (`retry_after_s`). Prøv igen: Ja, efter `Retry-After`. Eksempel på `error`: `rate limit exceeded`.

### 429 · quota_exceeded

Månedens kvote er brugt (eller sandbox-loftet for en testnøgle). Svaret bærer `X-Quota-*`-headere, og `Retry-After` peger på næste måned — prøv ikke igen automatisk. Body’et har kvoten (`limit`) og et link til at opgradere (`upgrade_url`). Prøv igen: Nej — ret kaldet. Eksempel på `error`: `monthly free-tier quota exceeded; upgrade to continue`.

### 429 · auth_throttled

For mange forsøg med ugyldige nøgler fra samme IP-adresse. Ret nøglen og vent det antal sekunder, `Retry-After` angiver. Prøv igen: Ja, efter `Retry-After`. Eksempel på `error`: `too many failed authentication attempts`.

### 500 · internal_error

En uventet fejl hos os. Den er logget med kaldets `X-Request-Id`; angiv det, hvis du kontakter support. Prøv igen: Ja, med backoff. Eksempel på `error`: `Internal Server Error`.

### 502 · upstream_error

Kilden (fx Datafordeler) svarede med fejl, efter vi har prøvet igen, og der var ingen brugbar cachet kopi. Prøv igen: Ja, med backoff. Eksempel på `error`: `upstream Datafordeler error`.

### 503 · source_unavailable

Kilden er ikke tilgængelig i øjeblikket, endpointet er ikke sat op i dette miljø (fx adresseindekset eller rumlige filtre), eller rate-limiteren er midlertidigt utilgængelig. Prøv igen: Ja, med backoff. Eksempel på `error`: `address search not enabled for this deployment`.

### 503 · not_yet_covered

Energimærke: ejendommen er ikke dækket endnu. Det er ikke det samme som "intet energimærke" — det ville være en 404. Prøv igen: Ja, med backoff. Eksempel på `error`: `BFE 5651067 is not yet covered by the energimærke corpus; …`.

### 504 · deadline_exceeded

Svaret tog længere end tidsgrænsen på ca. 20 sekunder. Arbejdet fortsætter i baggrunden, så et nyt kald er ofte hurtigt. Prøv igen: Ja, med backoff. Eksempel på `error`: `Gateway Timeout`.

## Hvilke fejl tæller

- **5xx og 504 tæller ikke.** Et kald, der ender i en serverfejl eller tidsgrænsen, lægges tilbage i månedens kvote.
- **400 tæller ikke.** Et kald, der afvises som forkert formet, før noget er slået op — `lng` for `lon`, et BFE-nummer med punktummer, en for kort søgetekst — bruger ingen enhed af månedens kvote. Det tæller stadig med i rate limit pr. minut.
- **Andre 4xx tæller med i kvoten.** Et opslag på et ukendt BFE-nummer (404) eller et kald uden adgang bruger én enhed, ligesom et vellykket kald. Et batch-kald, der afvises med `4xx`, bruger også kun én enhed, uanset hvor mange id’er det havde med.
- **Kun vellykkede svar faktureres.** Overforbrug på betalte planer beregnes ud fra svar under `400`.
- **402 og 429 tæller ikke.** Plan-tjekket og rate limits afviser kaldet, før det måles.

## Hvornår du skal prøve igen

- **429 fra burst-grænsen:** vent det antal sekunder, `Retry-After` angiver, og prøv igen. Kroppen bærer også `limit`, `window_s` og `retry_after_s`.
- **429 fra månedens kvote:** svaret bærer også `X-Quota-*`-headere og `upgrade_url` i kroppen, og `Retry-After` peger på næste måned. Prøv ikke igen automatisk.
- **502, 503 og 504:** prøv igen med eksponentiel backoff og jitter, fx 0,5 s, 1 s, 2 s. Stop efter nogle få forsøg.
- **400, 401, 402, 403 og 404:** prøv aldrig igen uden at ændre kaldet. Svaret bliver det samme.

```ts
const RETRYABLE = new Set([429, 502, 503, 504]);

export async function grundfastGet<T>(path: string, maxAttempts = 4): Promise<T> {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(`https://api.grundfast.dk${path}`, {
      headers: { Authorization: `Bearer ${process.env.GRUNDFAST_API_KEY}` },
    });
    if (res.ok) return (await res.json()) as T;

    // Månedens kvote er en 429 med X-Quota-*-headere: den forsvinder ikke ved at vente.
    const quotaExhausted = res.status === 429 && res.headers.has('X-Quota-Remaining');
    if (!RETRYABLE.has(res.status) || quotaExhausted || attempt >= maxAttempts) {
      const body = (await res.json().catch(() => ({}))) as { error?: string };
      throw new Error(`Grundfast ${res.status}: ${body.error ?? res.statusText}`);
    }

    const retryAfter = Number(res.headers.get('Retry-After'));
    const delayMs =
      retryAfter > 0 ? retryAfter * 1000 : 2 ** (attempt - 1) * 500 + Math.random() * 250;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }
}

// const ejendom = await grundfastGet('/v1/bbr/ejendom/5651067');
```

## Fejl i SDK’et

[TypeScript-SDK’et](https://grundfast.dk/docs/sdk) kaster en `GrundfastError` for ethvert svar uden for 2xx. Den har `status` (HTTP-statussen), `message` (teksten fra `error`), `retryAfter` (sekunder fra `Retry-After`, når headeren findes) og fejlsvarets `type`, `code`, `requestId`, `docUrl`, `localizedMessage` og — når API’et sender dem — `param` og `hint`. En timeout bliver til `status` 408.

```ts
import { GrundfastClient, GrundfastError } from '@grundfast/sdk';

const gf = new GrundfastClient({ apiKey: process.env.GRUNDFAST_API_KEY });

try {
  const ejendom = await gf.ejendom(5651067);
  console.log(ejendom.antal_bygninger);
} catch (err) {
  if (err instanceof GrundfastError && err.status === 404) {
    console.log('Ukendt BFE');
  } else if (err instanceof GrundfastError && err.type === 'plan_required') {
    console.log('Kræver en højere plan:', err.message);
  } else if (err instanceof GrundfastError && err.type === 'key_scope') {
    console.log('Nøglen mangler et scope:', err.message, err.requestId);
  } else {
    throw err;
  }
}
```

SDK’et prøver selv igen ved 408, 500, 502 og 503 og ved burst-429, med backoff og op til to ekstra forsøg som standard (`maxRetries`). Det prøver aldrig igen ved månedens kvote-429, og en eksport oprettes aldrig to gange. `504` prøves ikke igen automatisk, så håndtér den selv, hvis du vil.
