# Kvoter, grenser og feil

> Planer og kvoter, hva et «anlegg» er, hvor raskt du kan kalle hvert endepunkt, og hvordan feilsvar ser ut med status, error og code.

Kilde: https://solkart.no/api/dokumentasjon/grenser-og-feil · Sist oppdatert 2026-09-15 · Base-URL https://api.solkart.no · OpenAPI: https://solkart.no/openapi.json

## Planer

Prognose-endepunktene (`/api/forecast*`) styres av planen på nøkkelen. Tallene under er de som håndheves i koden i dag. Priser står på [priser](/priser).

| Plan | Forespørsler per døgn | Anlegg per døgn | Anlegg per bulk-kall | Maks kWp per anlegg | Utvidet prognose (`/extended`) | Døgnprognose (`daily`) | Koordinatoppløsning |
|---|---|---|---|---|---|---|---|
| Uten nøkkel (per IP) | 24 | 1 | 1 | 25 | Nei | Nei | 0,1° |
| Gratis | 24 | 1 | 1 | 25 | Nei | Nei | 0,1° |
| Basic | 1 000 | Kjøpt antall | Inntil 10 (begrenset av antall anlegg på nøkkelen) | 150 | Ja | Ja | 0,03° |
| Pro | 10 000 | Kjøpt antall | Inntil 50 (begrenset av antall anlegg på nøkkelen) | 1 000 | Ja | Ja | 0,03° |
| Enterprise | Ubegrenset | Ubegrenset | Ubegrenset | Ubegrenset | Ja | Ja | 0,03° |

TMY-endepunktene har egen teller: i lanseringsperioden får alle inntil 2000 forespørsler per døgn, med alle formater, produkter og P-verdier. Beregningene uten nøkkel (PV, snølast, snøtap, snøutsikt, terrenghorisont) har ingen kvote.

Tellerne for nøkler nullstilles 00:00 UTC. Telleren for kall uten nøkkel lever i 24 timer etter siste kall fra IP-adressen.

## Hva er et «anlegg»?

Ett anlegg er én unik koordinat du har spurt om i løpet av et døgn. Koordinaten rundes til planens oppløsning (0,1° på gratis, 0,03° på betalte planer) før den telles. Samme koordinat kan spørres om så mange ganger du vil innenfor forespørselskvoten; det er først en ny koordinat som bruker en plass. Flere takflater (`arrays`) på samme koordinat er fortsatt ett anlegg.

Når kvoten er brukt opp, får du `429` med detaljer:

```json
{
  "error": "Daglig anlegg-kvote brukt opp.",
  "details": "Du har 1 anlegg-plass på free-planen, og har allerede spurt om 1 unik koordinat i dag. Denne forespørselen ville lagt til 1 ny (1 avvist). Telleren nullstilles 00:00 UTC.",
  "what_is_anlegg": "Et \"anlegg\" er en unik koordinat (lat/lon snapet til tierens grid-oppløsning) i en 24-timersperiode. …",
  "quota": { "tier": "free", "limit": 1, "used": 1, "would_add": 1, "accepted": 0, "rejected": 1, "resets_at": "2026-09-16T00:00:00.000Z" },
  "rejected_coords": [ { "lat": 59.9, "lon": 10.8 } ],
  "upgrade": "https://solkart.no/api"
}
```

I bulk-kall avvises hele kallet når kvoten ikke rekker til alle nye koordinater; `quota.would_add` og `rejected_coords` viser hva som stoppet. Bruk `quota.resets_at` til å planlegge neste forsøk.

## Hastighetsgrenser

De tunge beregningene har grenser per sekund og per time, per IP-adresse i pilotperioden. Ved brudd får du `429` med `Retry-After` i sekunder.

| Endepunkt | Per sekund | Per time |
|---|---|---|
| `POST /api/horizon/rooftop` | 5 | 300 |
| `POST /api/horizon/precise` | 1 | 30 |
| `POST /api/terrain/category`, `POST /api/terrain/jobs` | 1 | 30 |
| `POST /api/roof/jobs`, `POST /api/roof/layout` | 1 | 20 |

Statuspolling på jobber (`GET /api/terrain/jobs/{id}`, `GET /api/roof/jobs/{id}`) teller ikke. Trenger du mer i produksjon, [kontakt oss](/kontakt) for en avtale med egne grenser og `X-Quota-Remaining` per bruker.

Prognose-endepunktene har ingen grense per sekund utover døgnkvoten, men prognosen oppdateres bare én gang i timen, så det er ingen grunn til å hente samme anlegg oftere. Se [caching](/api/dokumentasjon/caching-og-versjonering).

## Feilformat

Alle feil er JSON med `Content-Type: application/json` og feltet `error` med en forklaring på norsk (noen eldre meldinger i prognose-API-et er på engelsk). Endepunktene for horisont (nivå 2 og 3), terreng og tak legger til `code` i STORE_BOKSTAVER som du kan programmere mot. Ett unntak: `422` fra horisont nivå 2 og 3 når høydemodell mangler kommer rått fra beregningstjeneren som `{"detail": "…"}` uten `error`.

```json
{ "error": "lat må være et tall mellom 57 og 72.", "code": "INVALID_INPUT" }
```

| Status | Betyr | `code` (der den finnes) | Hva du bør gjøre |
|---|---|---|---|
| `400` | Ugyldig parameter, JSON eller koordinat utenfor Norge | `INVALID_INPUT` | Rett forespørselen. Ikke prøv på nytt uendret. |
| `401` | Manglende eller ugyldig nøkkel, eller døgnkvoten for kall er brukt | `UNAUTHENTICATED`, `PASSWORD_REQUIRED` | Sjekk nøkkelen; vent til nullstilling. |
| `402` | Nøkkelen har ingen anleggskvote, eller kvoten på en avtale er brukt opp | `QUOTA_EXHAUSTED` | Oppgrader eller vent til `quota_reset_at`. |
| `403` | Planen gir ikke tilgang (utvidet prognose, for mange anlegg, for mange kWp) | | Oppgrader, eller del opp forespørselen. |
| `404` | Ukjent jobb, ingen datacelle ved punktet, ingen høydemodell | `NOT_FOUND` | Sjekk id eller koordinat. |
| `405` | Feil HTTP-metode | `METHOD_NOT_ALLOWED` | Se `Allow`-hodet. |
| `409` | Jobben er ikke ferdig | `NOT_READY` | Poll status først. |
| `410` | Tegnegrunnlaget for en jobb er utløpt | `EXPIRED` | Kjør analysen på nytt. |
| `413` | For stor forespørsel | `TOO_LARGE` | Reduser innholdet. |
| `422` | Ingen bygning ved punktet, ingen datadekning | `NO_BUILDING`, `NO_COVERAGE` | Flytt punktet. |
| `429` | Anleggskvote eller hastighetsgrense | `RATE_LIMITED` | Vent `Retry-After` sekunder, eller til `resets_at`. |
| `500` | Intern feil | `FORMAT_ERROR` m.fl. | Prøv igjen; vedvarer det, [meld fra](/kontakt). |
| `502` | Bakenforliggende tjeneste svarte feil (MET, NVE, beregningstjener) | `BACKEND_ERROR` | Prøv igjen med økende ventetid (2, 4, 8 s). |
| `503` | Prognosedata mangler, kø full, tjeneste opptatt | `BACKEND_BUSY` | Vent `Retry-After` (standard 30 s) og prøv igjen. |
| `504` | Beregningen tok for lang tid | `BACKEND_TIMEOUT`, `TIMEOUT` | Prøv igjen, eller bruk jobb-endepunktet i kø. |

Ukjent sti under `/api/` på prognosetjeneren svarer `200` med en katalog over endepunkter, ikke `404`, og teller som ett kall. Sjekk derfor at svaret inneholder feltene du forventer, ikke bare statuskoden.

## Kvotestatus i hodene

Det finnes ingen `X-RateLimit-*`-hoder. Prognose-API-et gir kvotestatus i `429`-svaret (`quota`). Horisont nivå 2 og 3 setter `X-Quota-Remaining` (`unmetered` i pilot) og `X-Worker-Request-Id`, som du bør oppgi ved feilmeldinger til oss. Terreng- og takendepunktene setter bare fagspesifikke hoder (`X-Terrengkategori`, `X-Konfidens` på PDF/HTML; `X-Moduler`, `X-Kwp` på tegningen).

## Robust klient i praksis

- Sett tidsavbrudd: 15 s for prognose og TMY, 30 s for horisont nivå 2, 60 s for terrengkategori og horisont nivå 3, 120 s for takanalyse (eller bruk jobb-endepunktene).
- Prøv på nytt bare ved `429`, `502`, `503` og `504`, med `Retry-After` der det finnes, ellers eksponentiell ventetid med tilfeldig tillegg. Maks 3 forsøk.
- Aldri på nytt ved `400`, `401`, `402`, `403`, `422`.
- Logg `X-Worker-Request-Id` og `cycle_time`/`issued_utc` sammen med svaret.

## Helsesjekk

`GET https://api.solkart.no/health` svarer `{"status":"ok","auth_enabled":true}`. Det bekrefter at tjeneren svarer, ikke at prognosedata er ferske. Bruk `GET /api/forecast/latest` og sammenlign `cycle_time` med nå for å se om prognosen er oppdatert.