Referencia chýb

Všetky chyby API qr3.app sa riadia 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

Vstupné údaje neprešli validáciou schémy. Odpoveď obsahuje pole errors s podrobnosťami o konkrétnych poliach.

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

Príčiny: Chýbajúce povinné polia, nesprávne dátové typy, hodnoty mimo povoleného rozsahu, neplatný formát URL.

`errors/bad-request`

HTTP 400 Bad Request

Telo požiadavky nie je platný formát JSON, hoci je nastavená hlavička Content-Type: application/json (napr. čiarka za posledným prvkom, orezané alebo prázdne telo).

`errors/authentication`

HTTP 401 Unauthorized

API kľúč chýba, má nesprávny formát, vypršala jeho platnosť alebo bol odvolaný.

Riešenie: Skontrolujte, či je prítomná hlavička Authorization: Bearer qr3_sk_... a či je kľúč aktívny.

`errors/unauthorized`

HTTP 401 Unauthorized

Prichádzajúci webhook (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) bol zavolaný bez platného podpisu alebo tajného kľúča. Chýbajúci alebo neplatný API kľúč namiesto toho vracia chybu errors/authentication.

`errors/authorization`

HTTP 403 Forbidden

API kľúč je platný, ale nemá požadovaný rozsah (scope) alebo potrebné oprávnenie.

`errors/forbidden`

HTTP 403 Forbidden

Zdroj existuje, ale patrí inému workspace alebo inej organizácii.

`errors/document-immutable`

HTTP 403 Forbidden

Dokument DPP nahraný s parametrom is_immutable nie je možné vymazať.

`errors/not-found`

HTTP 404 Not Found

Požadovaný zdroj neexistuje alebo bol vymazaný.

`errors/conflict`

HTTP 409 Conflict

Zdroj s rovnakým jedinečným identifikátorom už existuje (napr. duplicitný slug alebo kolízia Idempotency-Key).

`errors/subscription-exists`

HTTP 409 Conflict

Volanie POST /v1/billing/checkout bolo vykonané, hoci organizácia už má predplatné. Zmeňte program radšej vo fakturačnom portáli.

`errors/rate-limited`

HTTP 429 Too Many Requests

Bol prekročený limit požiadaviek (rate limit) za minútu pre daný API kľúč. Odpoveď obsahuje hlavičky Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

Bol prekročený limit požiadaviek špecifický pre daný zdroj (napr. 200 QR kódov za deň na jeden workspace).

`errors/plan-limit`

HTTP 422 Unprocessable Entity

Váš aktuálny program neumožňuje túto akciu (napr. vyčerpaná kvóta DPP alebo dynamických kódov, príliš veľká dávka, príliš veľa workspaces alebo členov tímu). Vyžaduje sa upgrade.

`errors/invalid-file-type`

HTTP 400 Bad Request

Nahraný súbor má typ, ktorý koncový bod neakceptuje, alebo jeho obsah nezodpovedá deklarovanej hlavičke Content-Type.

`errors/file-too-large`

HTTP 413 Payload Too Large

Nahraný súbor prekračuje limit veľkosti programu alebo koncového bodu.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

Nahrávanie by prekročilo celkové úložisko workspace alebo DPP.

`errors/not-configured`

HTTP 503 Service Unavailable

Chýba požadovaná služba alebo konfigurácia (napr. nie je nakonfigurovaný Stripe, nie je nastavený API kľúč pre Web Risk).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

URL adresa bola zamietnutá, pretože ju služba Google Web Risk vyhodnotila ako nebezpečnú (malvér, phishing, sociálne inžinierstvo).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Vyhradené pre URL adresy, ktoré boli dodatočne vyhodnotené ako nebezpečné počas pravidelného opätovného skenovania (re-scanning).

`errors/already-submitted`

HTTP 409 Conflict

Duplicitné odoslanie — napr. pre tento workspace už bolo v tomto mesiaci odoslané hodnotenie NPS.

`errors/unprocessable-entity`

HTTP 422 Unprocessable Entity

Akcia administrátora nie je povolená (napr. vydávanie sa za iného superadmina). Tento typ vracajú iba koncové body pre superadmina.

`errors/request-error`

HTTP 4xx Client Error

Záložný typ pre chyby klienta bez špecifickejšieho typu; stav sa nachádza v odpovedi. API momentálne nemá žiadnu známu cestu, ktorá by ho vracala.

`errors/internal`

HTTP 500 Internal Server Error

Neočakávaná chyba na serveri. Skúste požiadavku zopakovať. V prípade pretrvávajúcich problémov kontaktujte: [email protected].