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/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/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/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/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 429 Too Many Requests

Aktuální tarif tuto akci neumožňuje (např. příliš mnoho Workspace). Je vyžadován upgrade.

`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/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].