Referenca napak

Vse napake API-ja qr3.app sledijo RFC 7807 Problem Details s 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

Vhodni podatki niso prestali validacije sheme. Odgovor vsebuje polje errors s podrobnostmi za posamezna polja.

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

Vzroki: Manjkajoča obvezna polja, napačni podatkovni tipi, vrednosti izven dovoljenega obsega, neveljaven format URL-ja.

`errors/bad-request`

HTTP 400 Bad Request

Telo zahteve ni veljaven JSON, čeprav je nastavljen Content-Type: application/json (npr. vejica za zadnjim elementom, odrezano ali prazno telo).

`errors/authentication`

HTTP 401 Unauthorized

Ključ API-ja manjka, je napačno formatiran, potekel ali preklican.

Rešitev: Preverite, ali je glava Authorization: Bearer qr3_sk_... prisotna in ali je ključ aktiven.

`errors/unauthorized`

HTTP 401 Unauthorized

Vhodni spletni kavelj (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) je bil klican brez veljavnega podpisa ali skrivnosti. Manjkajoč ali neveljaven API ključ namesto tega vrne odgovor errors/authentication.

`errors/authorization`

HTTP 403 Forbidden

Ključ API-ja je veljaven, vendar nima zahtevanega obsega (scope) ali potrebnih pravic.

`errors/forbidden`

HTTP 403 Forbidden

Vir obstaja, vendar pripada drugemu delovnemu prostoru (Workspace) ali drugi organizaciji.

`errors/document-immutable`

HTTP 403 Forbidden

Dokumenta DPP, ki je bil naložen z nastavitvijo is_immutable, ni mogoče izbrisati.

`errors/not-found`

HTTP 404 Not Found

Zahtevani vir ne obstaja ali pa je bil izbrisan.

`errors/conflict`

HTTP 409 Conflict

Vir z istim enoličnim identifikatorjem že obstaja (npr. podvojen slug ali kolizija ključa Idempotency-Key).

`errors/subscription-exists`

HTTP 409 Conflict

Klican je bil POST /v1/billing/checkout, čeprav organizacija že ima naročnino. Namesto tega spremenite paket v obračunskem portalu.

`errors/rate-limited`

HTTP 429 Too Many Requests

Omejitev števila zahtev (Rate-Limit) na minuto za ključ API-ja je bila presežena. Odgovor vsebuje glave Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining in X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

Presežena je bila omejitev števila zahtev (Rate-Limit), specifična za vir (npr. 200 QR-kod na dan na delovni prostor).

`errors/plan-limit`

HTTP 422 Unprocessable Entity

Vaš trenutni paket ne dovoljuje tega dejanja (npr. porabljena kvota DPP-jev ali dinamičnih kod, prevelika serija (batch), preveč delovnih prostorov ali članov ekipe). Potrebna je nadgradnja.

`errors/invalid-file-type`

HTTP 400 Bad Request

Naložena datoteka je vrste, ki je končna točka ne sprejema, ali pa se njena vsebina ne ujema z navedeno vrednostjo Content-Type.

`errors/file-too-large`

HTTP 413 Payload Too Large

Naložena datoteka presega omejitev velikosti paketa ali končne točke.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

Prenos bi presegel skupno shrambo delovnega prostora ali DPP-ja.

`errors/not-configured`

HTTP 503 Service Unavailable

Manjka zahtevana storitev ali konfiguracija (npr. Stripe ni konfiguriran, ključ API-ja Web Risk ni nastavljen).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

URL je bil zavrnjen, ker ga je Google Web Risk označil kot nevarnega (škodljiva programska oprema, ribarjenje, socialni inženiring).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Rezervirano za URL-je, ki so bili naknadno med periodičnim ponovnim preverjanjem označeni kot nevarni.

`errors/already-submitted`

HTTP 409 Conflict

Podvojena oddaja — npr. ocena NPS za ta delovni prostor je bila v tem mesecu že oddana.

`errors/unprocessable-entity`

HTTP 422 Unprocessable Entity

Dejanje administratorja ni dovoljeno (npr. lažno predstavljanje drugega superadmina). Ta tip vračajo samo končne točke za superadmina.

`errors/request-error`

HTTP 4xx Client Error

Nadomestni tip za napake odjemalca brez bolj specifičnega tipa; status je naveden v odgovoru. API trenutno nima znane poti, ki bi ga vračala.

`errors/internal`

HTTP 500 Internal Server Error

Nepričakovana napaka na strežniku. Prosimo, ponovite zahtevo. Če se težave nadaljujejo: [email protected].