Referenční příručka chyb

Všechny chyby rozhraní API qr3.app se řídí specifikací RFC 7807 Problem Details s hlavičkou 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í data neprošla validací schématu. Odpověď obsahuje pole errors s podrobnostmi pro jednotlivá pole.

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

Příčiny: Chybějící povinná pole, nesprávné datové typy, hodnoty mimo povolený rozsah, neplatný formát URL.

`errors/bad-request`

HTTP 400 Bad Request

Tělo požadavku není platný formát JSON, přestože je nastavena hlavička Content-Type: application/json (např. přebytečná čárka na konci, oříznuté nebo prázdné tělo).

`errors/authentication`

HTTP 401 Unauthorized

Klíč API chybí, má nesprávný formát, vypršela jeho platnost nebo byl odvolán.

Náprava: Zkontrolujte, zda je přítomna hlavička Authorization: Bearer qr3_sk_... a zda je klíč aktivní.

`errors/unauthorized`

HTTP 401 Unauthorized

Příchozí webhook (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) byl zavolán bez platného podpisu nebo tajného klíče. Chybějící nebo neplatný API klíč místo toho vrací chybu errors/authentication.

`errors/authorization`

HTTP 403 Forbidden

Klíč API je platný, ale nemá požadovaný rozsah (scope) nebo potřebné oprávnění.

`errors/forbidden`

HTTP 403 Forbidden

Zdroj existuje, ale patří jinému Workspace nebo jiné organizaci.

`errors/document-immutable`

HTTP 403 Forbidden

Dokument DPP nahraný s nastavením is_immutable nelze smazat.

`errors/not-found`

HTTP 404 Not Found

Požadovaný zdroj neexistuje nebo byl smazán.

`errors/conflict`

HTTP 409 Conflict

Zdroj se stejným jedinečným identifikátorem již existuje (např. duplicitní slug nebo kolize klíče Idempotency-Key).

`errors/subscription-exists`

HTTP 409 Conflict

Volání POST /v1/billing/checkout bylo provedeno, přestože organizace již má předplatné. Změňte tarif raději v portálu pro fakturaci.

`errors/rate-limited`

HTTP 429 Too Many Requests

Byl překročen minutový limit požadavků (rate limit) pro klíč API. Odpověď obsahuje hlavičky Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

Byl překročen limit požadavků specifický pro daný zdroj (např. 200 QR kódů za den na jeden Workspace).

`errors/plan-limit`

HTTP 422 Unprocessable Entity

Váš aktuální tarif neumožňuje tuto akci (např. vyčerpaná kvóta pro DPP nebo dynamické kódy, příliš velká dávka, příliš mnoho Workspaces nebo členů týmu). Je vyžadován upgrade.

`errors/invalid-file-type`

HTTP 400 Bad Request

Nahrávaný soubor má typ, který koncový bod nepřijímá, nebo jeho obsah neodpovídá deklarované hlavičce Content-Type.

`errors/file-too-large`

HTTP 413 Payload Too Large

Nahrávaný soubor překračuje limit velikosti pro daný tarif nebo koncový bod.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

Nahrání by překročilo celkovou kapacitu úložiště daného Workspace nebo DPP.

`errors/not-configured`

HTTP 503 Service Unavailable

Chybí požadovaná služba nebo konfigurace (např. není nakonfigurován Stripe, není nastaven klíč API pro Web Risk).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

Adresa URL byla zamítnuta, protože byla službou Google Web Risk vyhodnocena jako nebezpečná (malware, phishing, sociální inženýrství).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Vyhrazeno pro adresy URL, které byly dodatečně vyhodnoceny jako nebezpečné při pravidelném opakovaném skenování.

`errors/already-submitted`

HTTP 409 Conflict

Duplicitní odeslání — např. hodnocení NPS pro tento Workspace již bylo v tomto měsíci odesláno.

`errors/unprocessable-entity`

HTTP 422 Unprocessable Entity

Akce administrátora není povolena (např. impersonace jiného superadmina). Tento typ vrací pouze koncové body pro superadminy.

`errors/request-error`

HTTP 4xx Client Error

Záložní typ pro chyby klienta bez konkrétnějšího typu; stav je uveden v odpovědi. Rozhraní API v současné době nemá žádnou známou cestu, která by jej vracela.

`errors/internal`

HTTP 500 Internal Server Error

Neočekávaná chyba na serveru. Opakujte prosím požadavek. V případě přetrvávajících problémů kontaktujte: [email protected].