Virhekoodit

Vastauksen muoto: selain vs. ohjelmallinen kutsuja

Kaikki alla kuvatut virheet ovat JSON-muodossa oletuksena — myös kirjautumis-, tili- ja hallintanäkymien virheet, ei vain tällä sivulla kuvatut OAuth/OIDC-virheet. Tämä on oikea ja muuttumaton käytös machine API:lle ja jokaiselle ohjelmalliselle kutsujalle.

Jos pyynnön Accept-header pyytää text/html:aa (selaimen oletus lomakelähetyksissä), sama endpoint palauttaa sen sijaan brändätyn HTML-virhesivun samalla HTTP-statuksella ja headereilla (Retry-After mukaan lukien) — osoitetta ei tarvitse vaihtaa. Rate limitin 429 noudattaa samaa jakoa: JSON ohjelmalliselle kutsujalle, brändätty sivu selaimelle. Jos integroit ohjelmallisesti, älä lähetä Accept: text/html — silloin saat aina saman {"error": "..."}-rungon riippumatta siitä, mikä endpoint on kyseessä.

/token ja /introspect -virheet

Noudattavat RFC 6749 §5.2:ta. JSON-runko, jossa error-kenttä ja valinnainen error_description:

{
  "error": "invalid_client",
  "error_description": "unknown client"
}

Virhekoodi	HTTP	Milloin	Korjaus
invalid_request	400	grant_type puuttuu; pakollinen parametri (code, redirect_uri) puuttuu	Lisää puuttuva parametri
invalid_client	401	Tuntematon client_id; väärä client_secret; virheellinen todennus-header	Tarkista credentiaalit; käytä client_id:client_secret Basic-authia tai lomakekenttiä
invalid_grant	400	Koodia ei löydy, se on vanhentunut tai jo käytetty; refresh token peruutettu/vanhentunut; PKCE ei täsmää; redirect_uri ei täsmää authorize-pyyntöön	Pyydä uusi authorization; tarkista PKCE-toteutus
unauthorized_client	400	Client ei saa käyttää pyydettyä grant_type-arvoa	Salli grant-tyyppi clientille
unsupported_grant_type	400	grant_type ei ole authorization_code, refresh_token tai client_credentials	Käytä tuettua grant-tyyppiä
server_error	500	Sisäinen virhe (signing key puuttuu, tietokanta ei vastaa)	Yritä uudelleen; jos jatkuu, ota yhteyttä tenantin ylläpitoon

/authorize-virheet

Kun client_id ja redirect_uri ovat valideja, virheet palautetaan kyselyparametreina redirect-URIssa:

https://app.esimerkki.fi/callback?error=invalid_scope&error_description=Requested+scope+is+not+allowed&state=xyz

Kun client_id puuttuu, on tuntematon, tai redirect_uri ei ole rekisteröity, palvelin näyttää sen sijaan HTML-virhesivun — uudelleenohjaukseen ei voida luottaa, koska kohdetta ei ole validoitu (RFC 6749 §4.1.2.1). Sivun teksti on sama kaikissa kolmessa tapauksessa; jos päädyt tälle sivulle kehittäjänä, avaa sivun “Tietoa kehittäjälle” -kohta nähdäksesi mikä tarkalleen meni vikaan.

Virhekoodi	Milloin	Korjaus
unsupported_response_type	response_type ei ole code	Käytä response_type=code
unauthorized_client	Client on poistettu käytöstä	Ota client uudelleen käyttöön admin-paneelissa
invalid_scope	Pyydetty scope ei ole clientin allowed_scopes-listalla	Pyydä vain sallittuja scopeja, tai laajenna clientin scopet
invalid_request	code_challenge puuttuu kun PKCE pakollinen; tuntematon code_challenge_method	Lisää S256-PKCE; käytä code_challenge_method=S256
login_required	prompt=none, mutta käyttäjä ei ole kirjautunut tai tili ei kelpaa	Ohjaa käyttäjä interaktiiviseen kirjautumiseen (ilman prompt=none)

/revoke

Palauttaa aina HTTP 200 riippumatta siitä, löytyikö token (RFC 7009 §2.2). Virheitä esiintyy vain palvelinvirheissä.

Yleisimmät integraatiovirheet

“Saan invalid_grant-virheen joka kerta koodin vaihdossa”

1. Tarkista, että redirect_uri token-pyynnössä täsmää tarkalleen authorize-pyynnön arvoon (myös lopun kauttaviiva vaikuttaa).
2. Tarkista, ettei koodia ole jo käytetty — koodit ovat kertakäyttöisiä.
3. Tarkista, ettei koodi ole vanhentunut (voimassa 10 minuuttia).
4. Jos käytät PKCE:tä, varmista että code_verifier on oikea alkuarvo code_challenge:lle, joka lähetettiin /authorize-pyynnössä.

“Saan invalid_client-virheen vaikka credentiaalit ovat oikein”

• Käytä HTTP Basic -todennusta: Authorization: Basic base64(client_id:client_secret).
• Tai lähetä client_id ja client_secret lomakekenttinä pyynnön rungossa.
• Älä lähetä molempia — suosi Basic-authia.

“Saan invalid_scope-virheen”

Pyydetyn scopen täytyy olla clientin allowed_scopes-listan osajoukko. Oletusscopet ovat openid profile email. Pyydä offline_access-scope saadaksesi refresh tokenin.

“Tuntematon isäntänimi palauttaa 404”

tunnuspalvelu ei tarjoa oletustenanttia — Host-headerin täytyy täsmätä rekisteröityyn tenantin isäntänimeen tai sen aliakseen. Tarkista, että kutsut oikeaa domainia (esim. id.esimerkki.fi, ei esimerkki.fi).

Machine API -virheet

Machine API:n (/admin/*, HMAC-allekirjoitettu) virhemuoto ja -koodit poikkeavat OAuth-virheistä yllä — ks. Machine API — Virhekoodit.