Referenza tal-iŻbalji

L-iżbalji kollha tal-API ta’ qr3.app isegwu RFC 7807 Problem Details b’ 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

Id-dejta tal-input ma għaddietx mill-validazzjoni tal-iskema. Ir-rispons fih firxa (errors) b’dettalji preċiżi għal kull qasam.

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

Kawżi: Oqsma obbligatorji neqsin, tipi ta’ dejta żbaljati, valuri barra mill-firxa permessa, format tal-URL invalidu.

`errors/authentication`

HTTP 401 Unauthorized

Il-key tal-API hija nieqsa, f’format ħażin, skaduta jew revokata.

Soluzzjoni: Iċċekkja jekk l-header Authorization: Bearer qr3_sk_... huwiex preżenti u jekk il-key hijiex attiva.

`errors/authorization`

HTTP 403 Forbidden

Il-key tal-API hija valida, iżda m’għandhiex l-ambitu (scope) meħtieġ jew il-permess meħtieġ.

`errors/forbidden`

HTTP 403 Forbidden

Ir-riżorsa teżisti, iżda tappartjeni għal Workspace ieħor jew organizzazzjoni oħra.

`errors/not-found`

HTTP 404 Not Found

Ir-riżorsa mitluba ma teżistix jew ġiet imħassra.

`errors/conflict`

HTTP 409 Conflict

Riżorsa bl-istess identifikatur uniku diġà teżisti (eż. slug duplikat jew kolliżjoni tal-Idempotency-Key).

`errors/rate-limited`

HTTP 429 Too Many Requests

Il-limitu tar-rata (rate-limit) kull minuta tal-key tal-API ġie maqbuż. Ir-rispons fih l-headers Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining u X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

Limitu tar-rata speċifiku għar-riżorsa ġie maqbuż (eż. 200 QR-Codes kuljum għal kull Workspace).

`errors/plan-limit`

HTTP 429 Too Many Requests

Il-pjan attwali ma jippermettix din l-azzjoni (eż. wisq Workspaces). Meħtieġ upgrade.

`errors/not-configured`

HTTP 503 Service Unavailable

Servizz meħtieġ jew konfigurazzjoni hija nieqsa (eż. Stripe mhux ikkonfigurat, il-key tal-API ta’ Web Risk mhix issettjata).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

Il-URL ġiet miċħuda minħabba li ġiet ikklassifikata bħala mhux sigura minn Google Web Risk (Malware, Phishing, Social Engineering).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Riżervat għal URLs li sussegwentement jiġu kklassifikati bħala mhux siguri waqt skennjar mill-ġdid perjodiku.

`errors/already-submitted`

HTTP 409 Conflict

Sottomissjoni duplikata — eż. diġà ġie sottomess punteġġ NPS għal dan il-Workspace f’dan ix-xahar.

`errors/internal`

HTTP 500 Internal Server Error

Żball mhux mistenni fuq is-server. Jekk jogħġbok erġa’ pprova t-talba. Għal problemi persistenti: [email protected].