> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errori

> Formato e codici degli errori restituiti dall'API di GetQR.

> [!NOTE]
>
> L'API di GetQR è in beta ed è disponibile per alcuni workspace selezionati. I dettagli possono cambiare prima del rilascio generale.

L'API di GetQR usa i codici di stato HTTP standard. Le richieste riuscite restituiscono `2xx`. Quelle non riuscite restituiscono `4xx` o `5xx` con un corpo JSON che spiega cosa è andato storto.

## Formato degli errori

Ogni errore ha la stessa struttura: un codice stabile, un messaggio leggibile e un link alla descrizione di quel codice.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://getqr.com/account/api-docs#error-unauthorized"
  }
}
```

**error.code** `string` *required*

Codice di errore stabile e leggibile dalle macchine. Usalo nel tuo codice al posto del messaggio. Consulta [Codici di errore](#codici-di-errore).

**error.message** `string` *required*

Descrizione leggibile del problema. Il testo può cambiare.

**error.doc\_url** `string` *required*

Link alla descrizione del codice di errore nella documentazione API del tuo account GetQR.

## Codici di errore

| Codice | Stato HTTP | Quando si verifica |
| - | - | - |
| `bad_request` | 400 | La richiesta non è valida: il corpo non è JSON valido, all'header `Authorization` manca il prefisso `Bearer `, oppure l'azione non è consentita nello stato attuale della risorsa (ad esempio, annullare una creazione in blocco già terminata). |
| `unauthorized` | 401 | La chiave API manca o non è valida, ad esempio perché è stata rigenerata. |
| `forbidden` | 403 | L'abbonamento del proprietario del workspace non è attivo, oppure il tuo ruolo nel workspace non consente questa azione. |
| `exceeded_limit` | 403 | Hai raggiunto un limite del piano. Con il piano Single QR, succede quando crei o duplichi un QR code e il workspace ne ha già uno, o quando avvii una creazione in blocco. |
| `not_found` | 404 | La risorsa non esiste o non appartiene al tuo workspace, l'endpoint non esiste, oppure l'API non è abilitata per il tuo workspace. |
| `method_not_allowed` | 405 | L'endpoint esiste ma non accetta questo metodo HTTP. L'header `Allow` elenca i metodi accettati. |
| `conflict` | 409 | La richiesta è in conflitto con dati esistenti: lo slug del link breve è già occupato, una richiesta con la stessa `Idempotency-Key` è ancora in corso, una pianificazione si sovrappone a una esistente, oppure un archivio della creazione in blocco non è ancora pronto. |
| `invite_pending` | 409 | Sei stato invitato nel workspace ma non ti sei ancora unito. Le richieste con chiave API non lo restituiscono: il workspace della chiave è sempre uno di cui fai parte. |
| `invite_expired` | 410 | Il tuo invito al workspace è scaduto. Le richieste con chiave API non lo restituiscono, per lo stesso motivo. |
| `unprocessable_entity` | 422 | Il corpo o i parametri di query non hanno superato la validazione. Il messaggio indica il campo e cosa non va. Consulta [Errori di validazione](#errori-di-validazione). |
| `rate_limit_exceeded` | 429 | La chiave API ha esaurito le richieste per la finestra attuale. Consulta [Limiti di frequenza](https://docs.getqr.com/it/api/rate-limits.md). |
| `internal_server_error` | 500 | Qualcosa è andato storto da parte nostra. Riprova più tardi e contatta l'assistenza se il problema persiste. |

## Errori di validazione

Quando il corpo o i parametri di query non superano la validazione, l'API risponde `422`. Il messaggio descrive il primo campo non valido nel formato `<issue>: <field>: <details>`:

```json theme={null}
{
  "error": {
    "code": "unprocessable_entity",
    "message": "too_big: pageSize: Max page size is 100.",
    "doc_url": "https://getqr.com/account/api-docs#error-unprocessable_entity"
  }
}
```

I campi annidati usano la notazione con il punto, ad esempio `link.url`.

## Gestisci gli errori

* Basa la logica su `error.code`, non su `error.message`.
* Non ripetere senza modifiche le richieste con errori `4xx`: correggi prima la richiesta. Fanno eccezione un `409` per una richiesta ancora in corso e il `429`.
* In caso di `429`, attendi il numero di secondi indicato nell'header `Retry-After`. Consulta [Limiti di frequenza](https://docs.getqr.com/it/api/rate-limits.md#quando-superi-il-limite).
* Ripeti le richieste con errori `5xx` con un backoff esponenziale.

## Problemi comuni

> [accordion] Ogni richiesta restituisce 404 "This endpoint is not available."
>
> L'API è in beta e non è ancora abilitata per il tuo workspace.

> [accordion] 404 "This endpoint does not exist."
>
> Il percorso è errato. Confrontalo con le pagine degli endpoint e verifica che inizi con `/api/v1/`.

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> L'abbonamento del proprietario del workspace è terminato. La chiave API torna a funzionare appena il proprietario si abbona di nuovo.

> [accordion] 403 "API access is not available for this role."
>
> Il tuo ruolo nel workspace è Viewer. Solo il proprietario del workspace e gli Editor possono usare l'API.

## Passaggi successivi

> [card] [Limiti di frequenza](https://docs.getqr.com/it/api/rate-limits.md)

> [card] [Autenticazione](https://docs.getqr.com/it/api/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.