Hiba-referencia

Minden qr3.app API-hiba az RFC 7807 Problem Details szabványt követi Content-Type: application/problem+json fejléccel.

{
  "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

A bemeneti adatok nem mentek át a sémaellenőrzésen. A válasz (Response) egy errors tömböt tartalmaz mezőszintű részletekkel.

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

Okok: Hiányzó kötelező mezők, hibás adattípusok, a megengedett tartományon kívüli értékek, érvénytelen URL-formátum.

`errors/authentication`

HTTP 401 Unauthorized

Az API-kulcs hiányzik, hibás formátumú, lejárt vagy visszavont.

Megoldás: Ellenőrizze, hogy az Authorization: Bearer qr3_sk_... fejléc jelen van-e, és a kulcs aktív-e.

`errors/authorization`

HTTP 403 Forbidden

Az API-kulcs érvényes, de nem rendelkezik a szükséges hatókörrel (Scope) vagy jogosultsággal.

`errors/forbidden`

HTTP 403 Forbidden

Az erőforrás létezik, de egy másik Workspace-hez vagy szervezethez tartozik.

`errors/not-found`

HTTP 404 Not Found

A kért erőforrás nem létezik vagy törölve lett.

`errors/conflict`

HTTP 409 Conflict

Egy azonos egyedi azonosítóval rendelkező erőforrás már létezik (pl. duplikált slug vagy Idempotency-Key ütközés).

`errors/rate-limited`

HTTP 429 Too Many Requests

Az API-kulcs percenkénti korlátját (Rate-Limit) túllépte. A válasz tartalmazza a Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining és X-RateLimit-Reset fejléceket.

`errors/rate-limit`

HTTP 429 Too Many Requests

Egy erőforrás-specifikus korlát (Rate-Limit) túllépésre került (pl. 200 QR-kód naponta Workspace-enként).

`errors/plan-limit`

HTTP 429 Too Many Requests

A jelenlegi csomag nem teszi lehetővé ezt a műveletet (pl. túl sok Workspace). Csomagváltás (Upgrade) szükséges.

`errors/not-configured`

HTTP 503 Service Unavailable

Egy szükséges szolgáltatás vagy konfiguráció hiányzik (pl. a Stripe nincs konfigurálva, a Web Risk API-kulcs nincs beállítva).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

Az URL elutasításra került, mert a Google Web Risk nem biztonságosnak minősítette (malware, adathalászat, social engineering).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Fenntartva olyan URL-ek számára, amelyeket az időszakos ismételt vizsgálat (Re-Scanning) során utólag minősítettek nem biztonságosnak.

`errors/already-submitted`

HTTP 409 Conflict

Duplikált beküldés — például ebben a hónapban már beküldtek egy NPS-pontszámot ehhez a Workspace-hez.

`errors/internal`

HTTP 500 Internal Server Error

Váratlan hiba történt a szerveren. Kérjük, ismételje meg a kérést. Tartós problémák esetén: [email protected].