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
- Statuskoder
- Fejltyper
- 400 · invalid_request
- 401 · invalid_api_key
- 402 · plan_required
- 402 · seat_limit
- 403 · forbidden
- 403 · key_scope
- 403 · team_role
- 403 · cross_site_refused
- 403 · origin_not_allowed
- 403 · public_key_scope
- 404 · not_found
- 405 · method_not_allowed
- 409 · conflict
- 410 · job_rows_deleted
- 413 · payload_too_large
- 415 · unsupported_media_type
- 422 · unprocessable_parcel
- 422 · disposable_email
- 429 · rate_limited
- 429 · quota_exceeded
- 429 · auth_throttled
- 500 · internal_error
- 502 · upstream_error
- 503 · source_unavailable
- 503 · not_yet_covered
- 504 · deadline_exceeded
- Hvilke fejl tæller
- Hvornår du skal prøve igen
- Fejl i SDK’et
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å:
{
"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"
}typeer fejltypen — en af typerne i listen nedenfor og iGET /v1/errors. Forgren på den eller på HTTP-statussen, ikke på teksten.codeer den konkrete årsag, hvor vi kender den, fxapi_key_missingfrem forapi_key_invalid. Ellers er den lig medtype.messageer beskeden til et menneske, på dansk som standard og på engelsk, når kaldet senderAccept-Language: en. Hvor vi kender årsagen, står den her — fx atlatoglonser ud til at være byttet om — ellers en kort tekst for fejltypen. Svaret bærerContent-Language.param(kan forekomme) er den parameter, der er galt med, fxlonellerbfe.hint(kan forekomme) siger, hvad du skal sende i stedet, når vi kan læse det ud af kaldet:lngi stedet forlon, byttede koordinater, decimalkomma, et BFE-nummer skrevet med punktummer, eller nøglen sendt iX-API-Keyi stedet forAuthorization: Bearer.request_ider det samme somX-Request-Id-headeren. Angiv det, hvis du kontakter support om et bestemt kald.doc_urlpeger 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.
| 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 —
lngforlon, 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-Afterangiver, og prøv igen. Kroppen bærer ogsålimit,window_sogretry_after_s. - 429 fra månedens kvote: svaret bærer også
X-Quota-*-headere ogupgrade_urli kroppen, ogRetry-Afterpeger 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.
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.
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.