Klaidų žinynas

Visos qr3.app API klaidos atitinka RFC 7807 Problem Details su 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

Įvesties duomenys nepraėjo schemos patvirtinimo (validacijos). Atsakyme (Response) pateikiamas errors masyvas su tiksliomis laukų detalėmis.

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

Priežastys: Trūkstami privalomi laukai, neteisingi duomenų tipai, reikšmės už leistino diapazono ribų, neteisingas URL formatas.

`errors/authentication`

HTTP 401 Unauthorized

Trūksta API rakto, jis neteisingai suformatuotas, pasibaigęs jo galiojimas arba jis yra atšauktas.

Sprendimas: Patikrinkite, ar yra Authorization: Bearer qr3_sk_... antraštė (Header) ir ar raktas yra aktyvus.

`errors/authorization`

HTTP 403 Forbidden

API raktas yra galiojantis, tačiau neturi reikiamo Scope (srities) arba reikiamos teisės.

`errors/forbidden`

HTTP 403 Forbidden

Išteklius egzistuoja, tačiau priklauso kitai darbo sričiai (Workspace) arba kitai organizacijai.

`errors/not-found`

HTTP 404 Not Found

Užklaustas išteklius neegzistuoja arba buvo ištrintas.

`errors/conflict`

HTTP 409 Conflict

Išteklius su tuo pačiu unikaliu identifikatoriumi jau egzistuoja (pvz., pasikartojantis slug arba Idempotency-Key kolizija).

`errors/rate-limited`

HTTP 429 Too Many Requests

Viršytas API rakto užklausų limitas (Rate-Limit) per minutę. Atsakyme (Response) pateikiamos Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining ir X-RateLimit-Reset antraštės.

`errors/rate-limit`

HTTP 429 Too Many Requests

Viršytas konkretaus ištekliaus užklausų limitas (pvz., 200 QR kodų per dieną vienai darbo sričiai).

`errors/plan-limit`

HTTP 429 Too Many Requests

Esamas planas neleidžia atlikti šio veiksmo (pvz., per daug darbo sričių). Reikia atsinaujinti planą (Upgrade).

`errors/not-configured`

HTTP 503 Service Unavailable

Trūksta reikalingos paslaugos arba konfigūracijos (pvz., nekonfigūruotas Stripe, nenustatytas Web Risk API raktas).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

URL buvo atmestas, nes Google Web Risk jį įvertino kaip nesaugų (kenkėjiška programa, sukčiavimas, socialinė inžinerija).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Rezervuota URL adresams, kurie vėliau periodinio pakartotinio nuskaitymo (Re-Scanning) metu buvo įvertinti kaip nesaugūs.

`errors/already-submitted`

HTTP 409 Conflict

Dvigubas pateikimas — pvz., šiam Workspace šį mėnesį jau buvo pateiktas NPS įvertis.

`errors/internal`

HTTP 500 Internal Server Error

Netikėta serverio klaida. Bandykite užklausą dar kartą. Jei problema išlieka: [email protected].