Riferimento degli errori

Tutti gli errori dell’API qr3.app seguono lo standard RFC 7807 Problem Details con 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

I dati di input non hanno superato la validazione dello schema. La risposta contiene un array errors con i dettagli specifici per ciascun campo.

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

Cause: Campi obbligatori mancanti, tipi di dati errati, valori al di fuori dell’intervallo consentito, formato URL non valido.

`errors/authentication`

HTTP 401 Unauthorized

La chiave API manca, è formattata in modo errato, è scaduta o è stata revocata.

Risoluzione: Verifica che l’intestazione Authorization: Bearer qr3_sk_... sia presente e che la chiave sia attiva.

`errors/authorization`

HTTP 403 Forbidden

La chiave API è valida, ma non ha lo scope richiesto o i permessi necessari.

`errors/forbidden`

HTTP 403 Forbidden

La risorsa esiste, ma appartiene a un altro Workspace o a un’altra organizzazione.

`errors/not-found`

HTTP 404 Not Found

La risorsa richiesta non esiste o è stata eliminata.

`errors/conflict`

HTTP 409 Conflict

Esiste già una risorsa con lo stesso identificatore univoco (ad es. slug duplicato o collisione dell’Idempotency-Key).

`errors/rate-limited`

HTTP 429 Too Many Requests

Il limite di richieste (rate limit) al minuto per la chiave API è stato superato. La risposta contiene le intestazioni Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

È stato superato un limite di richieste specifico per la risorsa (ad es. 200 codici QR al giorno per Workspace).

`errors/plan-limit`

HTTP 429 Too Many Requests

Il piano attuale non consente questa azione (ad es. troppi Workspace). È necessario un upgrade.

`errors/not-configured`

HTTP 503 Service Unavailable

Manca un servizio o una configurazione richiesta (ad es. Stripe non configurato, chiave API di Web Risk non impostata).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

L’URL è stato rifiutato perché è stato classificato come non sicuro da Google Web Risk (malware, phishing, ingegneria sociale).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Riservato agli URL che sono stati successivamente classificati come non sicuri durante la scansione periodica ricorrente.

`errors/already-submitted`

HTTP 409 Conflict

Invio duplicato — ad es. è già stato inviato un punteggio NPS per questo Workspace in questo mese.

`errors/internal`

HTTP 500 Internal Server Error

Un errore imprevisto sul server. Si prega di riprovare la richiesta. In caso di problemi persistenti: [email protected].