Virheviite

Kaikki qr3.app API-virheet noudattavat RFC 7807 Problem Details -standardia otsikolla Content-Type: application/problem+json.

{
  "type": "https://docs.qr3.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "QR code qr_xxx not found"
}

`errors/validation`

HTTP 422 Unprocessable Entity

Syötetiedot eivät läpäisseet skeeman validointia. Vastaus sisältää errors-taulukon kenttäkohtaisilla tiedoilla.

{
  "type": "https://docs.qr3.app/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request body validation failed",
  "errors": [
    { "field": "url", "message": "Invalid URL format" }
  ]
}

Syyt: Puuttuvat pakolliset kentät, väärät tietotyypit, sallitun alueen ulkopuolella olevat arvot, virheellinen URL-muoto.

`errors/bad-request`

HTTP 400 Bad Request

Runko ei ole kelvollista JSON-muotoa, vaikka Content-Type: application/json on asetettu (esim. pilkku viimeisen elementin jälkeen, katkennut tai tyhjä runko).

`errors/authentication`

HTTP 401 Unauthorized

API-avain puuttuu, on virheellisessä muodossa, vanhentunut tai mitätöity.

Korjaus: Tarkista, onko Authorization: Bearer qr3_sk_... -otsikko mukana ja onko avain aktiivinen.

`errors/unauthorized`

HTTP 401 Unauthorized

Sisääntulevaa webhookia (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) kutsuttiin ilman voimassa olevaa allekirjoitusta tai salaisuutta. Puuttuva tai virheellinen API-avain palauttaa sen sijaan virheen errors/authentication.

`errors/authorization`

HTTP 403 Forbidden

API-avain on voimassa, mutta sillä ei ole vaadittavaa scopea tai tarvittavia oikeuksia.

`errors/forbidden`

HTTP 403 Forbidden

Resurssi on olemassa, mutta se kuuluu toiselle työtilalle (Workspace) tai organisaatiolle.

`errors/document-immutable`

HTTP 403 Forbidden

Asetuksella is_immutable ladattua DPP-dokumenttia ei voi poistaa.

`errors/not-found`

HTTP 404 Not Found

Pyydettyä resurssia ei ole olemassa tai se on poistettu.

`errors/conflict`

HTTP 409 Conflict

Resurssi samalla yksilöllisellä tunnisteella on jo olemassa (esim. kaksoiskappale slug-kentästä tai Idempotency-Key-törmäys).

`errors/subscription-exists`

HTTP 409 Conflict

Kutsuttiin POST /v1/billing/checkout, vaikka organisaatiolla on jo tilaus. Vaihda palvelupaketti sen sijaan laskutusportaalissa.

`errors/rate-limited`

HTTP 429 Too Many Requests

API-avaimen minuuttikohtainen pyyntöraja (Rate-Limit) on ylittynyt. Vastaus sisältää otsikot Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

Resurssikohtainen pyyntöraja (Rate-Limit) on ylittynyt (esim. 200 QR-koodia päivässä työtilaa kohden).

`errors/plan-limit`

HTTP 422 Unprocessable Entity

Nykyinen tilauksesi ei salli tätä toimintoa (esim. DPP- tai dynaamisten koodien kiintiö käytetty loppuun, eräkoko liian suuri, liikaa työtiloja tai tiimin jäseniä). Päivitys vaaditaan.

`errors/invalid-file-type`

HTTP 400 Bad Request

Ladatun tiedoston tyyppi ei ole päätepisteen hyväksymä, tai sen sisältö ei vastaa ilmoitettua Content-Type-arvoa.

`errors/file-too-large`

HTTP 413 Payload Too Large

Ladattu tiedosto ylittää palvelupaketin tai päätepisteen kokorajoituksen.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

Lataus ylittäisi työtilan tai DPP:n kokonaistallennustilan.

`errors/not-configured`

HTTP 503 Service Unavailable

Vaadittu palvelu tai konfiguraatio puuttuu (esim. Stripe-palvelua ei ole konfiguroitu, Web Risk API-avainta ei ole asetettu).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

URL hylättiin, koska Google Web Risk on luokitellut sen turvattomaksi (haittaohjelmat, tietojenkalastelu, sosiaalinen manipulointi).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Varattu URL-osoitteille, jotka on luokiteltu turvattomiksi jälkikäteen suoritetussa määräaikaisessa uudelleenskannauksessa (Re-Scanning).

`errors/already-submitted`

HTTP 409 Conflict

Kaksinkertainen lähetys — esim. NPS-tulos on jo lähetetty tälle työtilalle tässä kuussa.

`errors/unprocessable-entity`

HTTP 422 Unprocessable Entity

Ylläpitäjän toiminto ei ole sallittu (esim. toisen superadminin impersonointi). Vain superadmin-päätepisteet palauttavat tämän tyypin.

`errors/request-error`

HTTP 4xx Client Error

Varatyyppi asiakaspuolen virheille, joille ei ole tarkempaa tyyppiä; tila on vastauksessa. API:lla ei ole tällä hetkellä tiedossa olevaa polkua, joka palauttaisi sen.

`errors/internal`

HTTP 500 Internal Server Error

Odottamaton virhe palvelimella. Yritä pyyntöä uudelleen. Jos ongelma toistuu: [email protected].