Fel
Felstrukturen, vanliga felkoder och hur du hanterar dem.
Alla fel från Cerrtify returneras som ett JSON-svar med samma struktur:
{ "error": "error_code", "detail": "human-readable message" }Fältet error är en stabil, maskinläsbar kod; detail är ett läsbart meddelande som kan komma att ändras.
Vanliga felkoder
| Code | HTTP | Betydelse |
|---|---|---|
bad_json | 400 | Requestens body är inte giltig JSON |
invalid_request | 400 | Obligatoriskt fält saknas eller är felformaterat |
invalid_ip | 400 | endUserIp är inte en giltig IPv4-/IPv6-adress |
missing_orderRef | 400 | Fältet orderRef krävs men saknas |
invalid_orgnr | 400 | orgnr är inte ett giltigt 10-siffrigt organisationsnummer |
query_too_short | 400 | Företagssökningens q är kortare än 2 tecken |
query_too_long | 400 | Företagssökningens q är längre än 100 tecken |
missing_job_id | 400 | Inget jobb-ID i sökvägen — anropa /service/jobs/{id} |
read_body | 400 | Requestens body kunde inte läsas färdigt (bruten anslutning, fel Content-Length) |
no_active_qr_session | 404 | Ordern har ingen aktiv QR-session (redan slutförd eller avbruten) |
missing_api_key | 401 | Headern X-API-Key saknas |
invalid_api_key | 401 | Nyckeln finns inte eller har fel format |
unauthorized | 401 | Generellt autentiseringsfel |
insufficient_credits | 402 | Din organisation har slut på krediter (endast produktion) — fyll på i dashboarden. Obs: det här felet använder ett message-fält i stället för detail |
api_key_revoked | 403 | Nyckeln har återkallats i dashboarden |
api_key_expired | 403 | Nyckeln har passerat sitt expires_at |
organisation_inactive | 403 | Din organisation är inte längre aktiv |
insufficient_scope | 403 | Nyckeln saknar det scope som endpointen kräver (bankid, persondata eller company) |
spar_not_configured | 403 | Produktion: organisationen har inget SPAR-certifikat — ladda upp ett i dashboarden under Certifikat → SPAR |
ip_not_allowed | 403 | Anropets IP-adress finns inte i organisationens IP-allowlist |
origin_not_allowed | 403 | Webbläsarens Origin finns inte i din domänlista |
invalid_origin | 403 | Webbläsarens Origin-header är felformaterad |
job_not_found | 404 | Det asynkrona jobbets ID finns inte eller tillhör en annan organisation |
company_not_found | 404 | Endast sandbox: org.nr är inte ett av testföretagen i sandbox |
rate_limited | 429 | Rate limit för nyckeln har överskridits — försök igen efter tiden i Retry-After-headern |
search_failed | 500 | Sökningen i företagsregistret misslyckades på serversidan — försök igen och rapportera om det kvarstår |
internal | 500 | Oväntat serverfel vid läsning av ett asynkront jobb |
upstream_unavailable | 502 | Uppströmstjänsten ligger nere eller felar just nu — se Uppströmsavbrott |
bankid_response_parse | 502 | BankID svarade, men med en body vi inte kunde tolka |
upstream_parse_error | 502 | SPAR svarade, men med en body vi inte kunde tolka |
enqueue_failed | 503 | Kön för asynkrona jobb är inte tillgänglig |
audit_unavailable | 503 | Ett reglerat anrop (persondata, company) kunde inte granskningsloggas och nekades därför |
service_unavailable | 503 | En nödvändig uppströmstjänst (SPAR, BankID, Bolagsverket) är felkonfigurerad på serversidan |
Uppströmsavbrott
När en uppströmsleverantör inte går att nå eller returnerar serverfel svarar API:et med 502 och en standardiserad struktur som pekar ut den drabbade tjänsten:
{
"error": "upstream_unavailable",
"service": "bankid",
"message": "There is currently a problem with BankID. Please try again shortly."
}service är en av bankid, persondata eller company (fler kan tillkomma när nya tjänster lanseras). Problemet ligger hos leverantören — försök igen med backoff eller visa message för din användare.
Detta gäller endast riktiga avbrott. 4xx-protokollfel från leverantören (t.ex. ett ogiltigt BankID-orderRef) skickas fortfarande vidare oförändrade med leverantörens eget svar, så du behåller full felinformation.
Två andra 502-fel ingår inte i den strukturen: bankid_response_parse och upstream_parse_error. Där svarade leverantören, men med något vi inte kunde tolka, så det finns varken service eller message — bara error (och ibland detail). Hantera dem som upstream_unavailable: försök igen med backoff.