Virhetilanteet, ratkaisut ja usein kysytyt kysymykset

Tarkista, että olet suorittanut API-portaalin hyväksymistestauksen.

• Rajapintojen tuotantokäyttö edellyttää ohjelmistojen hyväksymistestausta. Ohjelmiston hyväksymistestaus tehdään itsepalveluna API-portaalissa. Testauksen suorittajalla tulee olla tuotantovarmenne.

Jos hyväksymistestausta ei ole suoritettu, rajapinnat palauttavat seuraavan virheen:

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

Tarkista API-portaaliin rekisteröidyn ohjelmiston tila, valitut rajapinnat ja kutsuissa käytetty API-avain.

• "HTTP 401 Unauthorized. Software key header is missing". Virheviesti annetaan, jos SoftwareKey-headeriä ei ole asetettu kutsuun ollenkaan tai header on annettu, mutta se ei sisällä API-avainta ollenkaan.
• "HTTP 401 Unauthorized. Software key is not associated to an application in the API portal". Virheviesti annetaan, jos API-avain ei ole aktiviinen, tai API-avain ei kuulu kyseiseen ohjelmistoon tai jos ohjelmisto ei ole aktiivinen API-portaalissa.
• "HTTP 401 Unauthorized. Software key is not integrated into the called service". Virheviesti annetaan, jos ohjelmisto ja API-avain ovat aktiivisia, mutta kyseistä rajapintaa/palvelua ei ole valittu ohjelmistoon API-portaalissa.

Lue lisää: Ohjelmiston rekisteröinti ja hyväksyntämenettely - vero.fi

Tarkista, että alla olevat header-tiedot on annettu jokaisessa API-kutsussa. Jos header-tietoja ei anneta, kaikki kutsut päätyvät virheeseen ja APIn käyttö estetään.

APIn käyttäjälle palautetaan seuraavat virheviestit, riippuen mikä tieto on puutteellinen:

• "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-tiedot:

• Accept: Header kertoo palvelimelle, minkä tyyppistä vastausta kutsuja odottaa. Yleensä käytetään arvoa application/json, joka tarkoittaa, että asiakas odottaa JSON-muotoista vastausta.
• Content-Type: Header määrittää, minkä tyyppistä dataa asiakas lähettää palvelimelle. Yleisin arvo on application/json, joka tarkoittaa, että lähetettävä data on JSON-muodossa.
• User-Agent: Header tunnistaa pyynnön lähettävän sovelluksen, käyttöjärjestelmän, laitteen ja/tai version. Tämä tieto auttaa palvelimia ja verkon osapuolia ymmärtämään, millainen järjestelmä tekee pyynnön.

Vero APIt edellyttävät lisäksi seuraavien headereiden käyttöä:

• Vero-softwarekey: Kaikki rajapinnat edellyttävät "vero-softwarekey" -headeria, johon asetetaan ohjelmistokohtainen API-avain.
• Vero-authorizationtoken: Headeria käytetään, mikäli rajapinta edellyttää Suomi.fi-valtuutta, kun asioidaan toisen asiakkaan puolesta.

Lue lisää: Vero API -rajapintojen tekniset linjaukset - vero.fi

Rajapinta palauttaa HTTP 429 (Too Many Requests) -vastauksen, kun rajapinnan käsittelykapasiteetti ylittyy.

Kutsujen määrän rajoittaminen (throttlaus) ja kuormituksen hallinta

Vero API -rajapinnat soveltavat throttlausta ja rate limitingiä palvelun vakauden ja tasapuolisen käytön varmistamiseksi. Tämä tarkoittaa, että palvelu valvoo sekä pyyntöjen saapumisnopeutta että samanaikaisten pyyntöjen määrää ja rajoittaa niitä dynaamisesti käytettävissä olevan kapasiteetin mukaan. Rajoitukset perustuvat tyypillisesti seuraaviin periaatteisiin:

• Nopeusrajoitus (rate limit): kuinka monta pyyntöä sallitaan tietyssä aikajaksossa (esim. pyyntöä/sekunti tai pyyntöä/minuutti).
• Burst-rajoitus: lyhytaikainen ylitys voidaan sallia, mutta vain rajattuun enimmäismäärään asti.
• Samanaikaisuusrajoitus (concurrency limit): kuinka monta pyyntöä voidaan käsitellä yhtä aikaa.
• Dynaaminen kuormansäätö: sallitut rajat voivat pienentyä tai kasvaa palvelun kokonaiskuormituksesta riippuen.

Jos jokin näistä rajoista ylittyy, rajapinta palauttaa vastauksen: HTTP 429 Too Many Requests

Toimintamalli rajapinnan käyttäjälle

Rajapinnan käyttäjän tulee toteuttaa asiakaspuolella kuormituksenhallinta seuraavien best practice -periaatteiden mukaisesti:

• Pyyntöjen tasaaminen
  • Vältä äkillisiä piikkejä (burst traffic)
  • Jaa kutsut tasaisesti ajassa (rate smoothing)
• Retry- ja backoff-strategia
  • HTTP 429 -tilanteessa pyyntöjä ei tule toistaa välittömästi, vaan käyttää viivästettyä uudelleenyritystä:
    • Hyödynnä eksponentiaalista backoffia
    • Lisää satunnaisviive (jitter) ruuhkahuippujen välttämiseksi

Esimerkki: 
1. yritys: heti
2. yritys: +1 s
3. yritys: +2 s
4. yritys: +4 s (+ satunnaisvaihtelu)

Samanaikaisuuden rajoittaminen

• Rajoita yhtäaikaisten säikeiden / rinnakkaisten kutsujen määrää
• Käytä esimerkiksi connection pool- tai worker-rajauksia

Idempotentit kutsut

• Suunnittele kutsut siten, että niiden turvallinen uudelleenlähetys on mahdollista

Mahdollisten vihjeiden hyödyntäminen

• Mikäli vastauksessa annetaan viitteitä odotusajasta (esim. Retry-After), noudata niitä

Tärkeää huomioida

• Tarkkoja numeerisia rajoja ei ole julkaistu, koska ne voivat muuttua dynaamisesti kuormitustilanteen mukaan.
• Rajoitukset voivat kohdistua eri tasoilla (esim. asiakas, tunniste, IP, sovellus).
• Rajoitusten tavoitteena on estää yksittäisen toimijan vaikutus koko palvelun saatavuuteen.

Varmenteisiin liittyvät virheviestit:

• Tietyissä varmenneongelmissa APIn käyttäjälle palautetaan seuraava virheviesti: "HTTP 403 Client certificate validation failed. Please check that the Vero API interface agreement is valid in the Certificate service".
• Tarkista aina kyseisen virheviestin kohdalla alla olevat asiat.

Rajapintaoikeudet eivät ole voimassa Varmennepalvelussa

• Tarkista, että olet hakenut Vero API -rajapintaoikeutta Varmennepalvelussa. Rajapintaoikeus pitää hakea erikseen testi- ja tuotantovarmenteille, riippuen kutsutko tuotannon rajapintoja vai testirajapintoja.
• Tyypillinen tilanne on se, että samaa Tiedon tuottaja Web Service -varmennetta käytetään Tulorekisteriin, Vero API-palveluun ja APItamoPKI-palveluun, mutta vain osa rajapintaoikeuksista on voimassa Varmennepalvelussa.
• Jos Vero API -rajapintaoikeus ei ole voimassa Varmennepalvelussa, kaikki API-kutsut päätyvät virheeseen.

Varmenne on vanhentunut

• Tarkista varmenteen voimassaoloaika Varmennepalvelusta.
• Hae uusi varmenne ajoissa tai käytä RenewCertificate PKI-rajapintaa vanhan varmenteen uusimiseen.
• Lue lisää: Varmenteen uusiminen - vero.fi

Testi- ja tuotantovarmenteiden käyttö

• Tarkista, että olet asettanut oikean tyyppisen varmenteen rajapintakutsuihin ohjelmistossasi.
• Vero API rajapinnoissa käytetään ainoastaan Tiedon tuottaja Web Service -varmennetyyppiä.
• Testirajapinnoissa käytetään testivarmennetta.
• Tuotantorajapinnoissa käytetään tuotantovarmennetta.
• API-portaalin hyväksymistestiskenaarioihin käytetään tuotantovarmennetta.
• Hiekkalaatikko ei vaadi varmenteen käyttöä.

Tarkista, vaatiiko APIn käyttö Suomi.fi-valtuutta.

• Jos suomi.fi valtuus ei ole voimassa, APIn käyttäjälle palautetaan seuraava virheviesti: "HTTP 1040 - No access to the requested data. Check that a valid authorization role exists in Suomi.fi authorization service."

Muita valtuuksiin liittyviä virheitä:

• Valtuus-token on vanhentunut. Token on voimassa aina 60 minuuttia kerrallaan.
• Tokeniin asetetut y-tunnukset, joiden puolesta asioidaan, ovat virheellisiä tai he eivät ole myöntäneet valtuutta tokenin käyttäjälle.

Vaatimus Suomi.fi valtuudesta on kerrottu jokaisen APIn rajapintadokumentaatiossa, API-portaalissa. Kaikki APIt eivät vaadi Suomi.fi valtuuksien käyttöä.

• Lue lisää: Puolesta asiointi - vero.fi

Virheellinen syöte tai yhteysongelmat.

• Tarkista, että ohjelmisto noudattaa rajapinnan dokumentaation mukaista skeemaa, sääntöjä ja muita tarkistuksia.
• Jos API-kutsun sisältö on virheellinen, APIn käyttäjälle palautetaan seuraava virheviesti: "HTTP 400, Bad Request".

Tarkista, että ohjelmisto ei kutsu rajapintoja yleisten katkoaikojen sisällä.

• Katkon aikana APIn käyttäjälle palautetaan seuraava virheviesti: "HTTP 500 Internal Server error".
• Lue lisää: Rajapintapalvelun saatavuus - vero.fi