# Felkoder

Alla felkoder i API:t och MCP med HTTP-status, betydelse och vad du gör.

Källa: https://getapi.gradientvibe.se/docs/fel

Ett fel har `status: "error"` och en `error.code` som går att bygga logik på. `error.message` är en förklaring på svenska. Samma koder gäller i MCP, där verktyget svarar med ett fel som innehåller koden.

Exempel: felaktigt organisationsnummer (HTTP 400):

```json
{
  "status": "error",
  "error": {
    "code": "invalid_org_number",
    "message": "Ange ett organisationsnummer med tio siffror, till exempel 569900-0013."
  }
}
```

## Alla felkoder

| Kod | HTTP | Betyder | Vad du gör |
| --- | --- | --- | --- |
| `unauthorized` | 401 | Nyckeln eller token saknas, är fel eller är återkallad. | Skicka `Authorization: Bearer gb_test_…` eller `gb_live_…`. Kontrollera att hela nyckeln kom med. En OAuth-token gäller en timme; förnya den med refresh-token. |
| `insufficient_scope` | 403 | Nyckeln saknar scopet som anropet kräver. | Skapa en nyckel med rätt scope under Konto → Nycklar. Se [scopes](https://getapi.gradientvibe.se/docs/autentisering#scopes). |
| `email_not_verified` | 403 | Användaren har inte bekräftat sin e-postadress. | Klicka på länken i bekräftelsemejlet, eller skicka ett nytt från Konto. |
| `user_disabled` | 403 | Användaren som äger nyckeln är avstängd. | Be kontots ägare att aktivera användaren, eller använd en egen nyckel. |
| `account_not_active` | 403 | Kontot är inte aktivt för live-data, till exempel under granskning. | Använd en testnyckel tills kontot är godkänt. Status syns under Konto. |
| `blocked_by_phase` | 503 | Live-data är inte öppnad ännu. Gäller live-nycklar och OAuth. | Använd en testnyckel mot sandlådan. Vi meddelar när live-data öppnar. Se [sandlådan](https://getapi.gradientvibe.se/docs/sandlada). |
| `suspended` | 503 | Åtkomsten är tillfälligt stoppad för nyckeln, kontot eller hela tjänsten. | Kontakta support@getbolag.se. |
| `rate_limited` | 429 | För många anrop per minut. | Vänta så många sekunder som `Retry-After` anger och försök igen. Se [takt och tak](https://getapi.gradientvibe.se/docs/takt-och-tak). |
| `search_quota_exceeded` | 429 | Kontot har gjort 1 000 sökningar i dag. | Vänta till nästa dygn, eller slå upp bolag direkt på organisationsnummer. |
| `entity_cap_exceeded` | 429 | Taket för antal olika bolag (och personer vars engagemang hämtas) per dygn är nått. | Bolag och personer du redan hämtat i dag går att hämta igen. Behöver du ett högre tak, kontakta support. |
| `insufficient_credits` | 402 | Krediterna räcker inte för anropet. | Fyll på under Konto → Krediter. |
| `monthly_cap_reached` | 402 | Kontots månadstak är nått. | Höj taket under Konto, eller vänta till nästa månad. |
| `key_daily_cap_reached` | 402 | Nyckelns eget dygnstak är nått. | Höj nyckelns tak under Konto → Nycklar, eller vänta till nästa dygn. |
| `invalid_org_number` | 400 | Organisationsnumret har fel form eller fel kontrollsiffra. | Skicka tio siffror, med eller utan bindestreck, till exempel `569900-0013`. |
| `invalid_query` | 400 | Sökningen saknas eller är tom. | Skicka `q` med ett namn eller ett organisationsnummer. |
| `query_too_short` | 400 | Namnsökningen har färre än fyra bokstäver eller siffror. | Skriv mer av namnet. |
| `invalid_since` | 400 | `since` är inte ett datum. | Skicka datumet som ÅÅÅÅ-MM-DD, till exempel `2026-01-01`. |
| `invalid_person_ref` | 400 | person_ref är okänd eller hör till ett annat konto. | Hämta personens person_ref på nytt via bolagets [roller](https://getapi.gradientvibe.se/docs/api/roller). |
| `invalid_parameter` | 400 | En parameter är okänd, upprepad eller har ett värde utanför intervallet. | Kontrollera parametrarna mot endpointens tabell. Okända parametrar avvisas i stället för att ignoreras. |
| `invalid_idempotency_key` | 400 | `Idempotency-Key` är tom, längre än 100 tecken eller innehåller annat än synliga ASCII-tecken. | Skicka ett kort, unikt värde per uppslag, till exempel ett UUID. |
| `idempotency_key_reused` | 422 | `Idempotency-Key` har redan använts för ett annat anrop (annan operation eller annat bolag). | Använd en ny nyckel för varje nytt uppslag. Samma nyckel gäller bara när exakt samma anrop görs om. Se [Idempotency-Key](https://getapi.gradientvibe.se/docs/takt-och-tak#idempotency-key). |
| `not_found` | 404 | Bolaget finns inte. | Kontrollera numret. Inte hittat debiteras inte. |
| `internal_error` | 500 | Något gick fel hos oss. | Försök igen med samma `Idempotency-Key`. Ange `request_id` om du kontaktar support. |
| `method_not_allowed` | 405 | Metoden stöds inte. API:t är skrivskyddat. | Använd GET. Headern `Allow` visar vilka metoder som gäller. |
| `not_configured` | 503 | Tjänsten är inte konfigurerad i miljön (svarar med `status: "not_configured"`). | Händer inte i produktion. Kontakta support om du ser det. |

## När du ska försöka igen

- `429`: vänta det antal sekunder som headern `Retry-After` anger.
- `500` och `unavailable` i `coverage`: försök igen med exponentiell väntetid och samma `Idempotency-Key`.
- `503 blocked_by_phase`: försök inte igen. Byt till en testnyckel tills live-data är öppnad.
- `400`, `402`, `403` och `404`: försök inte igen utan att ändra något.