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/bad-request`

HTTP 400 Bad Request

A törzs (body) nem érvényes JSON, bár a Content-Type: application/json be van állítva (például egy vessző az utolsó elem után, egy levágott vagy egy üres törzs).

`errors/authentication`

HTTP 401 Unauthorized

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

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

`errors/unauthorized`

HTTP 401 Unauthorized

Egy bejövő webhook (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) hívása érvényes aláírás vagy titkos kulcs nélkül történt. A hiányzó vagy érvénytelen API-kulcsra a rendszer ehelyett errors/authentication hibával válaszol.

`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/document-immutable`

HTTP 403 Forbidden

Az is_immutable beállítással feltöltött DPP-dokumentum nem törölhető.

`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/subscription-exists`

HTTP 409 Conflict

A POST /v1/billing/checkout hívása sikertelen, mert a szervezet már rendelkezik előfizetéssel. Módosítsd a csomagot inkább a számlázási portálon.

`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 422 Unprocessable Entity

A jelenlegi csomagod nem teszi lehetővé ezt a műveletet (pl. a DPP- vagy dinamikus kódkeret betelt, a batch túl nagy, vagy túl sok a Workspace, illetve a csapattag). Csomagváltás (upgrade) szükséges.

`errors/invalid-file-type`

HTTP 400 Bad Request

A feltöltött fájl típusa nem felel meg annak, amit a végpont elfogad, vagy a tartalma nem egyezik meg a megadott Content-Type értékkel.

`errors/file-too-large`

HTTP 413 Payload Too Large

A feltöltött fájl mérete meghaladja a csomag vagy a végpont által megengedett korlátot.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

A feltöltéssel a teljes tárhelyhasználat túllépné a Workspace vagy a DPP tárhelykeretét.

`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/unprocessable-entity`

HTTP 422 Unprocessable Entity

Egy adminisztrátori művelet nem engedélyezett (például egy másik superadmin megszemélyesítése). Csak a superadmin végpontok adják vissza ezt a típust.

`errors/request-error`

HTTP 4xx Client Error

Gyűjtőtípus olyan klienshibákhoz, amelyek nem rendelkeznek specifikusabb típussal; a státusz a válaszban található. Az API-nak jelenleg nincs olyan ismert végpontja, amely ezt adná vissza.

`errors/internal`

HTTP 500 Internal Server Error

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