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/bad-request`

HTTP 400 Bad Request

Užklausos kūnas nėra galiojantis JSON, nors nustatyta Content-Type: application/json (pavyzdžiui, kablelis po paskutinio elemento, nukirptas arba tuščias užklausos kūnas).

`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/unauthorized`

HTTP 401 Unauthorized

Įeinantis webhook adresas (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) buvo iškviestas be galiojančio parašo arba paslapties. Jei trūksta API rakto arba jis negalioja, vietoj to grąžinamas atsakymas errors/authentication.

`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/document-immutable`

HTTP 403 Forbidden

DPP dokumentas, įkeltas su nustatyta is_immutable reikšme, negali būti ištrintas.

`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/subscription-exists`

HTTP 409 Conflict

Buvo iškviestas POST /v1/billing/checkout, nors organizacija jau turi prenumeratą. Vietoj to pakeiskite planą atsiskaitymo portale.

`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 422 Unprocessable Entity

Dabartinis jūsų planas neleidžia atlikti šio veiksmo (pvz., išnaudota DPP ar dinaminių kodų kvota, per didelis paketas, per daug darbo sričių ar komandos narių). Reikia atnaujinti planą.

`errors/invalid-file-type`

HTTP 400 Bad Request

Įkelto failo tipas yra toks, kurio šis galinis taškas nepriima, arba jo turinys neatitinka nurodyto Content-Type.

`errors/file-too-large`

HTTP 413 Payload Too Large

Įkeltas failas viršija plane arba galiniame taške numatytą dydžio limitą.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

Įkėlus failą, būtų viršytas bendras darbo srities arba DPP saugyklos limitas.

`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/unprocessable-entity`

HTTP 422 Unprocessable Entity

Administratoriaus veiksmas neleidžiamas (pavyzdžiui, apsimetimas kitu superadminu). Tik superadmin galiniai taškai grąžina šį tipą.

`errors/request-error`

HTTP 4xx Client Error

Atsarginis klientų klaidų tipas, kai nėra konkretesnio tipo; būsena pateikiama atsakyme. Šiuo metu API neturi žinomo kelio, kuris jį grąžintų.

`errors/internal`

HTTP 500 Internal Server Error

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