Felsituationer, lösningar och vanliga frågor

Kontrollera att du har genomfört verifikationstesten i API-portalen.

• Användning av gränssnitt i produktion kräver verifikationstest av programvaran. Testet görs som självbetjäning i API-portalen. Den som utför testet måste ha ett produktionscertifikat.

Om testningen inte har genomförts returnerar gränssnittet följande fel:

• "HTTP 403 Forbidden. Production access not granted. All test scenarios must be passed first".

Kontrollera status för programvaran som är registrerad i API-portalen, valda gränssnitt och den API-nyckel som används i anropen:

• "HTTP 401 Unauthorized. Software key header is missing" – Felet uppstår om SoftwareKey-headern saknas helt eller inte innehåller någon API-nyckel.
• "HTTP 401 Unauthorized. Software key is not associated to an application in the API portal" – Felet uppstår om API-nyckeln inte är aktiv, inte tillhör programvaran eller om programvaran inte är aktiv i API-portalen.
• "HTTP 401 Unauthorized. Software key is not integrated into the called service" – Felet uppstår om programvaran och API-nyckeln är aktiva, men det aktuella gränssnittet inte har valts i API-portalen.

Läs mer: Registrering av programvara och godkännandeförfarande – vero.fi

Kontrollera, att följande headers anges i varje API-anrop. Om någon av dessa saknas leder det till fel och API-användningen blockeras.

Följande felmeddelanden returneras beroende på vilken header som saknas:

• "HTTP 400 Bad Request. Missing HTTP Header: Accept".
• "HTTP 403 Forbidden Microsoft-Azure-Application-Gateway/v2".
• "HTTP 400 Bad Request. Missing HTTP Header: User-Agent".

Header-information:

• Accept: Anger vilket svarsinnehåll klienten förväntar sig. Vanligt värde: application/json.
• Content-Type: Anger vilket format klienten skickar data i. Vanligt värde: application/json.
• User-Agent: Identifierar applikationen, operativsystemet, enheten och/eller versionen som gör anropet.

Skatteförvaltningens API:er kräver dessutom följande headers:

• Vero-softwarekey: Alla gränssnitt kräver denna header med programvaruspecifik API-nyckel.
• Vero-authorizationtoken: Används om gränssnittet kräver Suomi.fi-fullmakt för att agera för någon annan.

Läs mer: Tekniska riktlinjer för Vero API-gränssnitten – vero.fi

HTTP 429 (Too Many Requests)-felet returneras när för många samtidiga anrop görs till gränssnittet eller när antalet anrop överskrider gränssnittets behandlingskapacitet.

Begränsning av antalet anrop (throttling) och hantering av belastningen
 
Gränssnitten Vero API tillämpar throttling och rate limiting för att säkra stabiliteten i tjänsten och en objektiv användning. Detta innebär att tjänsten övervakar både den hastighet som anropen kommer med och antalet samtidiga anrop och begränsar dem enligt den dynamiskt tillgängliga kapaciteten. Begränsningarna grundar sig typiskt på följande principer:

• Hastighetsbegränsning (rate limit): hur många anrop som tillåts inom en viss tid (till exempel anrop/sekund eller anrop/minut)
• Burst-begränsning: en kortvarig överskridning kan tillåtas, men endast upp till en begränsad maximal nivå.
• Begränsning av samtidighet (concurrency limit): hur många anrop kan behandlas samtidigt.
• Dynamisk belastningsjustering: de tillåtna gränserna kan minska eller växa beroende på helhetsbelastningen av tjänsten.

Om någon av dessa gränser överskrids returnerar gränssnittet svaret: HTTP 429 Too Many Requests
 
Handlingsplan för dem som använder gränssnittet
 
Användaren av gränssnittet ska implementera hanteringen av belastningen på kundsidan enligt följande best practice-principer:

• Jämn fördelning av anrop
  • Undvik plötsliga toppar (burst traffic)
  • Fördela anropen jämnt tidsmässigt (rate smoothing)
• Retry- och backoffstrategin
  • I situationer med HTTP 429 ska anropen inte upprepas omedelbart utan fördröjt nytt försök ska användas:
    • Utnyttja expotentiell backoff
    • Lägg till slumpmässig fördröjning (jitter) för att undvika rusningstoppar 

Ett exempel:
1. Försök 1: genast
2. Försök 2: +1 s
3. Försök 3: +2 s
4. Försök 4: +4 s (+ slumpmässig variation)

Begränsning av samtidighet

• Begränsa antalet samtidiga trådar / parallella anrop
• Använd exempelvis begränsningarna pool eller worker

Idempotenta anrop

• Planera anropen så att det är möjligt att skicka dem säkert på nytt

Att utnyttja eventuella ledtrådar

• Om svaret antyder om väntetid (till exempel Retry-After) ska du följa det

Viktigt att notera

• Inga exakta numeriska gränser har publicerats eftersom de kan ändras dynamiskt beroende på belastningssituationen.
• Begränsningarna kan riktas till olika nivåer (t.ex. kund, identifierare, IP, applikation).
• Syftet med begränsningarna är att förhindra att en enskild aktör påverkar tillgången till hela tjänsten.

Fel relaterade till certifikat:

• Vid vissa certifikatproblem returneras: "HTTP 403 Client certificate validation failed. Please check that the Vero API interface agreement is valid in the Certificate service".

Kontrollera följande vid detta fel:

Gränssnittsbehörigheter saknas i Certifikattjänsten:

• Kontrollera att du har ansökt om API-behörighet i Certifikattjänsten. Behörighet måste ansökas separat för test- och produktionscertifikat.
• Ett vanligt scenario är att samma certifikat används för Inkomstregistret, Skatteförvaltningens API och APItamoPKI, men endast vissa behörigheter är giltiga.
• Om API-behörigheten inte är giltig returnerar alla anrop fel.

Certifikatet har gått ut:

• Kontrollera certifikatets giltighetstid i Certifikattjänsten.
• Ansök om nytt certifikat i tid eller använd RenewCertificate-gränssnittet. Läs mer: Förnyande av certifikat – vero.fi

Användning av test- och produktionscertifikat:

• Kontrollera att rätt typ av certifikat används i anropen.
• Endast certifikat av typen "Tiedon tuottaja Web Service" används.
• Testgränssnitt kräver testcertifikat.
• Produktionsgränssnitt kräver produktionscertifikat.
• Verifikationstest i API-portalen kräver produktionscertifikat.
• Sandbox kräver inte certifikat.

Kontrollera om API-användningen kräver Suomi.fi-fullmakt.

• Om fullmakt saknas returneras: "HTTP 1040 - No access to the requested data. Check that a valid authorization role exists in Suomi.fi authorization service."

Andra fel relaterade till fullmakter:

• Fullmaktstoken har gått ut (giltig i 60 minuter).
• FO-numren i token är felaktiga eller har inte beviljat fullmakt.

Kravet på Suomi.fi-fullmakt anges i varje API:s dokumentation i API-portalen. Alla API:er kräver inte fullmakt.

• Läs mer: Att sköta ärenden för någon annans räkning via Vero API-gränssnitt –vero.fi

Felaktig data eller anslutningsproblem:

• Kontrollera att programvaran följer gränssnittets schema, regler och valideringar.
• Vid felaktigt innehåll returneras: "HTTP 400, Bad Request"

Anrop under driftavbrott:

• Under avbrott returneras: "HTTP 500 Internal Server error"
• Läs mer: Tillgänglighet för gränssnitt – vero.fi