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

> ## Agent Instructions
> Documentazione di dentalspace. Il testo completo, incluso il riferimento API, è in /llms-full.txt. Per endpoint, campi e codici di errore la fonte di verità è openapi.json: non usare endpoint o campi non documentati.

# Limiti di richiesta

> Quante richieste per clinica e per chiave, header X-RateLimit-* e Retry-After, risposta 429.

## Limiti

| Di chi | Ogni 10 secondi | Al giorno |
| - | - | - |
| Clinica, sommando tutte le sue chiavi | 100 | 20.000 |
| Singola chiave | 60 | 12.000 |

Il giorno è il giorno di calendario UTC: riparte a mezzanotte UTC. Una richiesta respinta con `429` non consuma il limite.

Il tetto per chiave impedisce a un solo programma di consumare tutto il limite della clinica: due programmi collegati con chiavi diverse non si fermano a vicenda.

## Header

Ogni risposta a una richiesta con una chiave valida, errori compresi, porta questi header:

| Header | Valore |
| - | - |
| `X-RateLimit-Limit` | Il tetto della finestra più stretta in quel momento, fra le quattro della tabella sopra |
| `X-RateLimit-Remaining` | Le richieste rimaste in quella finestra |
| `X-RateLimit-Reset` | Quando quella finestra riparte, in secondi Unix (UTC) |
| `X-RateLimit-Daily-Limit` | Il tetto giornaliero più stretto |
| `X-RateLimit-Daily-Remaining` | Le richieste rimaste oggi |
| `X-RateLimit-Daily-Reset` | Quando riparte il giorno, in secondi Unix |
| `Retry-After` | Solo sul `429`: i secondi da aspettare, almeno `1` |

Una richiesta senza chiave o con una chiave sconosciuta non riceve gli header `X-RateLimit-*`. Ogni risposta porta invece `X-Request-Id`.

```http theme={null}
HTTP/1.1 200 OK
X-Request-Id: req_6f1c2a0e4b8d4c6e9a512f3b7d8e9a10
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1790000060
```

## Risposta 429

Oltre il limite l'API risponde `429 rate_limited`. In `details`: `limit` è il tetto che ha fermato la richiesta, `window` quale finestra (`10s` o `day`), `scope` di chi è il limite (`organization` per la clinica, `api_key` per la chiave), `resetAt` quando riparte, in ISO 8601.

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

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "Troppe richieste: rallenta e riprova dopo Retry-After secondi.",
    "details": {
      "limit": 60,
      "window": "10s",
      "scope": "api_key",
      "resetAt": "2026-10-02T14:14:07.000Z"
    },
    "requestId": "req_6f1c2a0e4b8d4c6e9a512f3b7d8e9a10"
  }
}
```

Aspetta i secondi di `Retry-After`, poi ripeti. Per non arrivarci, rallenta quando `X-RateLimit-Remaining` si avvicina a zero.

<Tip>
  Per ripetere una creazione dopo un `429`, usa la stessa [`Idempotency-Key`](/api/idempotenza).
</Tip>


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