> ## 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.

# Limiti di frequenza

> Quante richieste puoi inviare e come gestire le risposte 429.

> [!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 limita il numero di richieste che ogni chiave API può inviare, così una singola integrazione non può rallentare l'API per tutti.

## Limiti

| Limite | Valore |
| - | - |
| Richieste per chiave API | 600 al minuto |

Il limite viene calcolato su una finestra mobile di un minuto e si applica a tutti gli endpoint insieme. Il [controllo dello stato](https://docs.getqr.com/it/api/endpoints/health.md) non richiede una chiave e non viene conteggiato.

## Header dei limiti di frequenza

Le risposte alle richieste con una chiave API valida includono questi header, comprese le risposte di errore:

| Header | Descrizione |
| - | - |
| `X-RateLimit-Limit` | Numero massimo di richieste per finestra. |
| `X-RateLimit-Remaining` | Richieste rimanenti nella finestra attuale. |
| `X-RateLimit-Reset` | Quando la finestra si azzera, come timestamp Unix in millisecondi. |
| `Retry-After` | Secondi mancanti all'azzeramento della finestra, arrotondati per eccesso. Attendi questo tempo prima di riprovare. |

## Quando superi il limite

Oltre il limite, l'API risponde `429` con il codice `rate_limit_exceeded` e gli stessi header:

```http theme={null}
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1792764060000
Retry-After: 37

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests.",
    "doc_url": "https://getqr.com/account/api-docs#error-rate_limit_exceeded"
  }
}
```

Attendi l'orario di azzeramento prima di inviare altre richieste. Aggiungi un jitter, così più worker non riprovano nello stesso istante, e usa un backoff esponenziale sugli errori `5xx`:

```javascript theme={null}
async function getqrFetch(url, options = {}, maxRetries = 5) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, {
      ...options,
      headers: {
        Authorization: `Bearer ${process.env.GETQR_API_KEY}`,
        ...options.headers,
      },
    });

    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || attempt >= maxRetries) return res;

    // On 429, wait for Retry-After (seconds). Otherwise back off: 1s, 2s, 4s…
    const retryAfter = Number(res.headers.get("Retry-After"));
    const wait =
      res.status === 429 && retryAfter > 0
        ? retryAfter * 1000
        : 1000 * 2 ** attempt;
    const jitter = Math.random() * 250;

    await new Promise((r) => setTimeout(r, wait + jitter));
  }
}
```

> [!TIP]
>
> Ripeti `POST /api/v1/qrs` solo con un header `Idempotency-Key`. Così un nuovo tentativo non crea mai un secondo QR code. Consulta [Idempotenza](https://docs.getqr.com/it/api/introduction.md#idempotenza).

## Resta sotto il limite

* Controlla `X-RateLimit-Remaining` e rallenta prima che arrivi a 0.
* Usa le [creazioni di QR in blocco](https://docs.getqr.com/it/api/endpoints/bulk-qr-creations.md) invece di una richiesta per ogni QR code.
* Recupera fino a 100 risultati per pagina con `pageSize=100`. Consulta [Paginazione](https://docs.getqr.com/it/api/introduction.md#paginazione).
* Metti in cache le immagini dei QR: i download restituiscono un `ETag`, quindi puoi inviare `If-None-Match` e ricevere `304 Not Modified` se non è cambiato nulla.

## Passaggi successivi

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

> [card] [QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md)


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