Yleiset virhetilanteet ja ratkaisut

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.

Huomioi: Testirajapintojen (apitest.vero.fi) palomuurisääntöjä on kiristetty maanantaina 12.5.2025, jolloin Header-tiedot tulivat pakollisiksi kaikille käyttäjille.

Tuotannossa (api.vero.fi) headerit tulivat pakollisiksi 17.9.2025 alkaen

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

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