Referenca pogrešaka

Sve pogreške qr3.app API-ja slijede 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

Ulazni podaci nisu prošli validaciju sheme. Odgovor sadrži polje errors s detaljima za svako pojedino polje.

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

Uzroci: Nedostajuća obavezna polja, neispravni tipovi podataka, vrijednosti izvan dopuštenog raspona, neispravan format URL-a.

`errors/bad-request`

HTTP 400 Bad Request

Tijelo zahtjeva nije valjan JSON iako je postavljen Content-Type: application/json (npr. zarez nakon zadnjeg elementa, skraćeno ili prazno tijelo).

`errors/authentication`

HTTP 401 Unauthorized

API ključ nedostaje, neispravno je formatiran, istekao je ili je opozvan.

Rješenje: Provjerite je li zaglavlje Authorization: Bearer qr3_sk_... prisutno i je li ključ aktivan.

`errors/unauthorized`

HTTP 401 Unauthorized

Dolazni webhook (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) pozvan je bez valjanog potpisa ili tajnog ključa. Nedostajući ili nevažeći API ključ umjesto toga odgovara s errors/authentication.

`errors/authorization`

HTTP 403 Forbidden

API ključ je valjan, ali nema potreban opseg (scope) ili potrebnu ovlast.

`errors/forbidden`

HTTP 403 Forbidden

Resurs postoji, ali pripada drugom radnom prostoru (Workspace) ili drugoj organizaciji.

`errors/document-immutable`

HTTP 403 Forbidden

DPP dokument učitan s parametrom is_immutable ne može se obrisati.

`errors/not-found`

HTTP 404 Not Found

Zatraženi resurs ne postoji ili je obrisan.

`errors/conflict`

HTTP 409 Conflict

Resurs s istim jedinstvenim identifikatorom već postoji (npr. dvostruki slug ili kolizija Idempotency-Key-a).

`errors/subscription-exists`

HTTP 409 Conflict

POST /v1/billing/checkout je pozvan iako organizacija već ima pretplatu. Umjesto toga promijenite plan na portalu za naplatu.

`errors/rate-limited`

HTTP 429 Too Many Requests

Prekoračeno je ograničenje učestalosti (rate limit) po minuti za API ključ. Odgovor sadrži zaglavlja Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

Prekoračeno je ograničenje učestalosti specifično za resurs (npr. 200 QR kodova dnevno po radnom prostoru).

`errors/plan-limit`

HTTP 422 Unprocessable Entity

Vaš trenutni plan ne dopušta ovu akciju (npr. iskorištena kvota za DPP-ove ili dinamičke kodove, prevelika serija, previše radnih prostora ili članova tima). Potrebna je nadogradnja.

`errors/invalid-file-type`

HTTP 400 Bad Request

Učitana datoteka je tipa koji krajnja točka ne prihvaća ili njezin sadržaj ne odgovara deklariranom Content-Type.

`errors/file-too-large`

HTTP 413 Payload Too Large

Učitana datoteka premašuje ograničenje veličine vašeg plana ili krajnje točke.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

Učitavanje bi premašilo ukupnu pohranu radnog prostora ili DPP-a.

`errors/not-configured`

HTTP 503 Service Unavailable

Nedostaje potrebna usluga ili konfiguracija (npr. Stripe nije konfiguriran, API ključ za Web Risk nije postavljen).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

URL je odbijen jer ga je Google Web Risk klasificirao kao nesiguran (zlonamjerni softver, krađa identiteta, socijalni inženjering).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Rezervirano za URL-ove koji su naknadno klasificirani kao nesigurni tijekom periodičkog ponovnog skeniranja.

`errors/already-submitted`

HTTP 409 Conflict

Dvostruko slanje — npr. NPS ocjena za ovaj radni prostor već je poslana ovog mjeseca.

`errors/unprocessable-entity`

HTTP 422 Unprocessable Entity

Radnja administratora nije dopuštena (npr. lažno predstavljanje drugog superadmina). Samo krajnje točke za superadmina vraćaju ovaj tip.

`errors/request-error`

HTTP 4xx Client Error

Rezervni tip za pogreške klijenta bez specifičnijeg tipa; status se nalazi u odgovoru. API trenutno nema poznatu putanju koja ga vraća.

`errors/internal`

HTTP 500 Internal Server Error

Neočekivana pogreška na poslužitelju. Molimo ponovite zahtjev. Ako se problemi nastave: [email protected].