Spring til indhold

Grundfast

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.

På denne side· 6 afsnit

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å:

403
{
  "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 og i GET /v1/errors. 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, med en stabil type pr. fejltype.

StatusBetydning i GrundfastPrøv igen?
400Ugyldig 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.
401Nø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.
402Funktionen 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.
403Kontoen 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.
404Ressourcen findes ikke: ukendt BFE, UUID, CVR-nummer, kode eller sti.Nej — ret kaldet.
405Stien 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.
409Ressourcen 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.
410Et 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.
413Request-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.
415Et konto-endpoint fik et body, der ikke er application/json. Send Content-Type: application/json.Nej — ret kaldet.
422Jordstykket 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.
429Burst-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.
500En uventet fejl hos os. Den er logget med kaldets X-Request-Id; angiv det, hvis du kontakter support.Ja, med backoff.
502Kilden (fx Datafordeler) svarede med fejl, efter vi har prøvet igen, og der var ingen brugbar cachet kopi.Ja, med backoff.
503Kilden 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.
504Svaret 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.
grundfast-fetch.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 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.

fejl.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.