Felkatalog

Varje fel från API:t har en stabil kod i fältet error. Förgrena på koden, inte på texterna.

Felsvaret ser alltid ut så här:

{
  "error": "invalid_orgnr",
  "message": "Organisationsnumret har fel kontrollsiffra.",
  "hint": "Kontrollera numret eller använd GET /v1/validate/{orgnr}.",
  "docs_url": "https://api.registry.gothiaai.se/docs/errors#invalid_orgnr",
  "request_id": "req_5c2d90a1e7b34f68a10d"
}

message och hint är till för människor och kan ändras utan varsel. error ändras inte inom en version.
Nya koder kan tillkomma utan ny version. Hantera en okänd kod som ett vanligt fel utifrån HTTP-statusen.
Fel kostar aldrig enheter. De räknas däremot mot gränsen per minut, utom 401 och 429.
Bara det första problemet i ett anrop rapporteras. Parametrarna kontrolleras i ordningen land, limit, q, sni, legal_form, city, filterkravet. Med filter kontrolleras land, att inga andra sökparametrar används, limit och sedan själva uttrycket.
I ett batch-anrop blir ett enskilt nummer som inte går att slå upp ett error-objekt i resultatet, med HTTP-status 200 för anropet. Då gäller felkoderna för organisationsnummer nedan.

Nyckel och gränser

missing_api_key

HTTP-status: 401
Orsak: Headern Authorization saknas, eller börjar inte med Bearer .
Åtgärd: Skicka Authorization: Bearer rg_live_... på varje anrop under /v1.

invalid_api_key

HTTP-status: 401
Orsak: Nyckeln är okänd, har fel format (ska börja med rg_live_ eller rg_test_ och vara 20 till 80 tecken), är återkallad, har gått ut eller hör till ett avstängt konto. Det går medvetet inte att se skillnad, så att ingen kan pröva sig fram till vilka nycklar som finns.
Åtgärd: Kontrollera att hela nyckeln är kopierad utan mellanslag eller radbrytningar. Skapa en ny nyckel i utvecklarportalen om du har återkallat den eller tappat den. Är kontot avstängt, kontakta oss.

rate_limited

HTTP-status: 429
Orsak: Nyckeln har gjort fler anrop än planen tillåter under den här minuten (UTC-klockminut). Planen free tillåter 10. Vissa planer har dessutom en gräns per slutanvändare bakom en delad nyckel; den ger samma fel.
Åtgärd: Vänta det antal sekunder som står i Retry-After (och i X-RateLimit-Reset) och försök igen. Sprid anropen över tid. Behöver du högre gräns, byt plan.
Rubriker: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining (0), X-RateLimit-Reset

quota_exceeded

HTTP-status: 429
Orsak: Kontot har förbrukat månadens enheter. Kvoten delas av alla nycklar på kontot. Gäller anrop som kostar enheter: GET /v1/companies/{orgnr}, GET /v1/companies och POST /v1/companies/batch. Kvoten kontrolleras före anropet, så ett batch-anrop som startade under gränsen kan ha tagit förbrukningen över den.
Åtgärd: Vänta inte i sekunder: kvoten nollställs den 1:a i nästa månad klockan 00:00 UTC (meddelandet anger datumet). Byt plan för fler enheter. GET /v1/validate/{orgnr} och GET /v1/usage fungerar fortfarande och kostar inget.
Rubriker: Retry-After (sekunder till periodens slut)

control_plane_unavailable

HTTP-status: 503
Orsak: Vi kunde inte kontrollera nyckeln just nu, eftersom kontosystemet inte svarade. En nyckel som har använts nyligen fortsätter fungera i upp till tio minuter under ett sådant avbrott, så felet drabbar främst nya nycklar.
Åtgärd: Försök igen efter Retry-After sekunder (5), med växande väntetid om det fortsätter. Fortsätter det i mer än några minuter, kontakta oss med request_id.
Rubriker: Retry-After

Organisationsnummer

invalid_orgnr

HTTP-status: 400 (i batch: ett error-objekt i resultatet)
Orsak: Numret är inte tio siffror (efter att mellanslag, ett bindestreck och SCB:s prefix 16 på tolvsiffriga nummer tagits bort), är längre än 20 tecken, innehåller mer än ett bindestreck eller bokstäver, eller har fel kontrollsiffra (Luhn). Meddelandet säger vilket.
Åtgärd: Rätta numret. Du kan fråga GET /v1/validate/{orgnr} först: det kostar ingenting och talar om om det är formatet eller kontrollsiffran som är fel.
Kostnad: 0 enheter

not_a_company

HTTP-status: 404 (i batch: ett error-objekt i resultatet)
Orsak: Numret har formen av ett personnummer (tredje siffran är 0 eller 1) och slås därför aldrig upp. Det är avsiktligt: tjänsten ska inte kunna användas för att ta reda på om en person driver verksamhet. Kontrollsiffran spelar ingen roll för det här.
Åtgärd: Det går inte att slå upp numret. Enskilda firmor ingår inte i registret.
Kostnad: 0 enheter

company_not_found

HTTP-status: 404 (i batch: ett error-objekt i resultatet)
Orsak: Numret är giltigt men finns inte i registret. Vanliga skäl: numret är nytt och registret laddas bara om veckovis, bolaget är en enskild firma (ingår inte), eller numret är felaktigt men råkar ha rätt kontrollsiffra.
Åtgärd: Kontrollera numret med GET /v1/validate/{orgnr}. Försök igen efter nästa veckoladdning om bolaget är nytt (meta.data_as_of visar senaste laddningen på andra anrop).
Kostnad: 0 enheter

unsupported_country

HTTP-status: 400
Orsak: Parametern country (eller country i batch-kroppen) har något annat värde än SE.
Åtgärd: Utelämna parametern eller använd SE. Version 1 täcker bara Sverige.

Sökning

invalid_limit

HTTP-status: 400
Orsak: limit är inte ett heltal mellan 1 och 100, eller är över 10 när q (namnsökning) används.
Åtgärd: Använd ett värde från 1 till 100, eller från 1 till 10 med q. Utelämnad limit ger 20 (10 med q). Vill du ha fler träffar per anrop: sök utan q med filter, där varje bolag kostar en enhet.

invalid_query

HTTP-status: 400
Orsak: q är kortare än 2 eller längre än 100 tecken efter rengöring. Tecknen %, _ och \ ersätts med mellanslag, flera mellanslag blir ett och kanterna trimmas. En sökning på %% blir alltså tom.
Åtgärd: Skriv minst två bokstäver av bolagsnamnet.

invalid_sni

HTTP-status: 400
Orsak: sni är inte 2 till 5 siffror.
Åtgärd: Exempel: sni=62 (alla bolag vars primära SNI-kod börjar med 62) eller sni=62100.

invalid_legal_form

HTTP-status: 400
Orsak: legal_form har fel format. Tillåtet är 1 till 6 bokstäver, eventuellt följt av bindestreck och 1 till 10 bokstäver.
Åtgärd: Exempel: legal_form=AB eller legal_form=AB-ORGFO (Bolagsverkets kod). Versaler och gemener fungerar.

invalid_city

HTTP-status: 400
Orsak: city är längre än 60 tecken.
Åtgärd: Ange bara ortnamnet, till exempel city=Göteborg. En ort som inte finns ger en tom lista, inte det här felet.

invalid_filter

HTTP-status: 400
Orsak: Uttrycket i filter går inte att tolka eller använder något som inte finns: ett okänt fält, en operator som fältet inte stöder, ett värde av fel typ eller form, ett tecken som inte ingår i språket, eller en kombination med q, sni, city eller legal_form. Meddelandet anger positionen (tecken räknat från 1) och vad som förväntades.
Åtgärd: Rätta uttrycket enligt meddelandet. Fälten, operatorerna och exemplen står i guiden. Skriv villkoren som en del av filter i stället för att kombinera dem med de andra parametrarna.
Kostnad: 0 enheter

filter_too_complex

HTTP-status: 400
Orsak: Uttrycket överskrider en gräns: högst 1 000 tecken, 20 villkor, 5 nivåer av parenteser och NOT, och 100 värden i en IN-lista.
Åtgärd: Förenkla uttrycket eller dela upp sökningen i flera anrop.
Kostnad: 0 enheter

filter_too_broad

HTTP-status: 400
Orsak: Uttrycket matchar nästan hela registret (över 500 000 bolag enligt vår uppskattning, till exempel bara legal_form = 'AB'). En lista över hela registret kan inte hämtas.
Åtgärd: Lägg till villkor som avgränsar urvalet: bransch (sni), ort (city), storlek (employee_class) eller registreringsdatum.
Kostnad: 0 enheter

filter_unavailable

HTTP-status: 503
Orsak: Tabellen som filter söker i är inte laddad just nu, till exempel under en ny driftsättning.
Åtgärd: Försök igen efter Retry-After sekunder. q, sni, city och legal_form fungerar under tiden.
Rubriker: Retry-After
Kostnad: 0 enheter

server_busy

HTTP-status: 503
Orsak: Tjänsten har många sökningar igång samtidigt och din fick inte plats inom två sekunder, eller så svarade databasen inte i tid (en fråga som tog över åtta sekunder avbryts). Det är inget fel i ditt anrop.
Åtgärd: Försök igen efter Retry-After sekunder. Fördröj gärna omförsöket och skicka inte flera sökningar parallellt.
Rubriker: Retry-After
Kostnad: 0 enheter

page_limit_exceeded

HTTP-status: 400
Orsak: Kontots plan begränsar hur många sidor en sökning får bläddra, och din cursor leder förbi gränsen. Gäller bara planer med sidgräns.
Åtgärd: Avgränsa sökningen med fler villkor i stället för att bläddra djupare, eller använd ett konto med en större plan.
Kostnad: 0 enheter

batch_not_allowed

HTTP-status: 403
Orsak: Kontots plan får inte använda POST /v1/companies/batch. Gäller bara vissa särskilda planer.
Åtgärd: Hämta ett bolag i taget med GET /v1/companies/{orgnr}, eller använd ett konto med en plan som tillåter batch.
Kostnad: 0 enheter

missing_filter

HTTP-status: 400
Orsak: Sökningen har varken q eller något av sni, city och legal_form. En lista över hela registret kan inte hämtas.
Åtgärd: Lägg till minst ett villkor, till exempel /v1/companies?sni=62&city=Göteborg.

invalid_cursor

HTTP-status: 400
Orsak: cursor går inte att tolka: den är ändrad, avkortad, längre än 400 tecken, eller hör till en annan sorts sökning (en cursor från en sökning med q fungerar inte utan q, och tvärtom).
Åtgärd: Skicka next_cursor oförändrad, med exakt samma övriga parametrar som i anropet som gav den. Starta annars om utan cursor.

cursor_expired

HTTP-status: 410
Orsak: Registret har laddats om sedan sökningen startade. Gäller sökningar med q: en cursor är bara giltig inom en dataladdning. Sökningar utan q påverkas inte.
Åtgärd: Starta om sökningen utan cursor. Bolag som du redan har hämtat kan komma igen, så ta bort dubbletter på orgnr.

Batch

missing_orgnrs

HTTP-status: 400
Orsak: Kroppen saknar orgnrs, eller listan är tom.
Åtgärd: Skicka {"orgnrs": ["556123-4567"]} med 1 till 100 nummer och Content-Type: application/json.

too_many_orgnrs

HTTP-status: 400
Orsak: Listan har fler än 100 nummer.
Åtgärd: Dela upp anropet i omgångar om högst 100. Tänk på gränsen per minut när du skickar många omgångar.

Övrigt

internal_error

HTTP-status: 500
Orsak: Något gick fel hos oss.
Åtgärd: Försök igen med växande väntetid. Fortsätter det, kontakta oss och ange request_id.
Kostnad: 0 enheter

Svar utan felkod

Fyra situationer ger ett tomt svar utan JSON-kropp, eftersom de avvisas av webbramverket innan API:ts egen felhantering. Nyckeln kontrolleras alltid först, så de kräver giltig nyckel och räknas mot gränsen per minut. De kostar inga enheter.

404: sökvägen finns inte under /v1.
405: fel HTTP-metod för sökvägen, till exempel POST mot /v1/usage.
400: kroppen i POST /v1/companies/batch är inte giltig JSON. Skiljs från missing_orgnrs, som är ett svar med felkod och gäller giltig JSON utan orgnrs.
415: POST /v1/companies/batch skickades utan Content-Type: application/json.

Behandla ett svar utan JSON-kropp som ett vanligt fel utifrån HTTP-statusen, och kontrollera Content-Type på svaret innan du läser det som JSON.