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

HTTP 400 Bad Request

Il body non è un JSON valido, sebbene sia impostato Content-Type: application/json (ad esempio, una virgola finale di troppo, un body troncato o vuoto).

`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/unauthorized`

HTTP 401 Unauthorized

Un webhook in entrata (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) è stato chiamato senza una firma o un segreto validi. Se la chiave API è mancante o non valida, viene restituito invece errors/authentication.

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

HTTP 403 Forbidden

Un documento DPP caricato con is_immutable non può essere eliminato.

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

HTTP 409 Conflict

POST /v1/billing/checkout è stato chiamato sebbene l’organizzazione abbia già un abbonamento. Modifica invece il piano nel portale di fatturazione.

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

Il tuo piano attuale non consente questa azione (ad es. quota di DPP o codici dinamici esaurita, batch troppo grande, troppi workspace o membri del team). È necessario un upgrade.

`errors/invalid-file-type`

HTTP 400 Bad Request

Il file caricato è di un tipo non accettato dall’endpoint, oppure il suo contenuto non corrisponde al Content-Type dichiarato.

`errors/file-too-large`

HTTP 413 Payload Too Large

Il file caricato supera il limite di dimensioni del piano o dell’endpoint.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

Il caricamento supererebbe lo spazio di archiviazione totale del workspace o del DPP.

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

HTTP 422 Unprocessable Entity

Un’azione di amministrazione non è consentita (ad esempio, l’impersonificazione di un altro superadmin). Solo gli endpoint di superadmin restituiscono questo tipo.

`errors/request-error`

HTTP 4xx Client Error

Fallback per gli errori client senza un tipo più specifico; lo stato si trova nella risposta. L’API attualmente non ha alcun percorso noto che lo restituisca.

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