Controlla la quota di una chiave API

Leggi le quote attuali di titolare e chiave senza consumare la quota principale.

GET/v1/rate-limit

Accesso: Serve una chiave API Bearer
Client: Client locale o server

Esempi di richiesta#

cURL

curl -fsS -H "Authorization: Bearer $VEIL_API_KEY" \
  "https://veil.rip/v1/rate-limit"

Risposta#

HTTP 200application/json

owner, metadati key, quota, rate, resource e retryAfter. quota distingue richieste condivise, verifiche, eventuale quota giornaliera ed eventuale limite della chiave. Gli orari usano secondi Unix.

Campo	Tipo	Significato
`owner`	`integer`	Numero permanente della scheda titolare.
`key`	`ApiKey`	Metadati della chiave autenticata, mai il segreto.
`quota`	`Quota`	Quote condivise di richieste e verifiche, più eventuali limiti giornalieri e della chiave. Questa lettura non consuma la quota principale.
`rate`	`Bucket`	Quota descritta dalle intestazioni del limite nella risposta.
`resource`	`string`	Risorsa descritta da rate.
`retryAfter`	`integer`	Secondi prima che una richiesta possa essere ammessa; può essere positivo anche se questa lettura restituisce 200.

Esempio di risposta

Valori illustrativi. Leggi la risposta corrente della tua richiesta.

json

{
  "owner": 1,
  "key": {
    "id": "0123456789abcdef0123456789abcdef",
    "owner": 1,
    "label": "Website backend",
    "prefix": "veil_live_01234567…",
    "scopes": [
      "read",
      "verify"
    ],
    "state": "active",
    "createdAt": "2026-10-27T00:00:00Z",
    "expiresAt": "2027-01-25T00:00:00Z",
    "revokedAt": null,
    "suspended": false,
    "requestsPerMinute": null,
    "lastUsedAt": null,
    "requests": 0
  },
  "quota": {
    "requests": {
      "limit": 600,
      "remaining": 600,
      "resetAt": 1793059200
    },
    "verification": {
      "limit": 120,
      "remaining": 120,
      "resetAt": 1793059200
    },
    "daily": null,
    "key": null
  },
  "rate": {
    "limit": 600,
    "remaining": 600,
    "resetAt": 1793059200
  },
  "resource": "requests",
  "retryAfter": 0
}

Apri un oggetto annidato per leggerne i campi. I tipi con null ammettono un valore null; i campi optional possono essere assenti. Gli altri campi sono presenti nell’oggetto.

Metadati della chiave API ApiKey

Campo	Tipo	Significato
`id`	`string`	ID pubblico di gestione della chiave, non il segreto Bearer.
`owner`	`integer`	Numero permanente della scheda titolare.
`label`	`string`	Etichetta dell’integrazione scelta dal titolare.
`prefix`	`string`	Prefisso visualizzato non segreto.
`scopes`	`array<string>`	read e/o verify.
`state`	`string`	active, expired, suspended o revoked. La sospensione dell’account è indicata separatamente.
`createdAt`	`string`	Data e ora di creazione in ISO 8601 UTC.
`expiresAt`	`string`	Scadenza in ISO 8601 UTC.
`revokedAt`	`string \| null`	Data e ora della revoca permanente.
`suspended`	`boolean`	Indica se questa chiave è sospesa.
`requestsPerMinute`	`integer \| null`	Limite aggiuntivo della chiave, oppure null.
`lastUsedAt`	`string \| null`	Ultimo uso ammesso, oppure null se mai usata.
`requests`	`integer`	Richieste ammesse durante la vita della chiave.

Quote condivise e aggiuntive Quota

Campo	Tipo	Significato
`requests`	`Bucket`	Quota di richieste condivisa dal titolare.
`verification`	`Bucket`	Quota di verifica condivisa aggiuntiva. Una verifica consuma entrambe le quote.
`daily`	`Bucket \| null`	Limite giornaliero aggiuntivo, se impostato.
`key`	`Bucket \| null`	Limite aggiuntivo della singola chiave, se impostato.

Quota Bucket

Campo	Tipo	Significato
`limit`	`integer`	Capacità della quota, oppure limite del giorno UTC per la quota giornaliera.
`remaining`	`integer`	Richieste intere disponibili al momento.
`resetAt`	`integer`	Secondi Unix in cui la quota sarà piena, oppure la prossima mezzanotte UTC per il limite giornaliero.

Intestazioni della risposta#

Intestazione	Valore	Significato
`Content-Type`	`application/json`	Usa il tipo dichiarato per scegliere come leggere il corpo.
`Date`	`HTTP date`	Ora del server. Confrontala con il tuo orologio per firmare le richieste.
`Cache-Control`	`no-store`	Non conservare le risposte private o temporanee in una cache condivisa.
`Retry-After`	`integer seconds, on rate_limited or busy`	Attendi almeno questo intervallo prima di riprovare. Altri codici 429/503 non lo includono necessariamente.
`X-RateLimit-Limit`	`integer`	Capacità della quota indicata.
`X-RateLimit-Remaining`	`integer`	Richieste intere rimaste nella quota.
`X-RateLimit-Reset`	`Unix seconds`	Istante in cui la quota sarà piena, non il confine di una finestra fissa al minuto.
`X-RateLimit-Resource`	`requests \| verification \| key \| daily`	Quota rappresentata dalle intestazioni. Gli altri saldi sono in quota.

Note d’uso#

La risposta è privata e usa Cache-Control no-store.
Anche le richieste pubbliche autenticate con Bearer restituiscono X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset e X-RateLimit-Resource. Sono intestazioni per client locali o server; il CORS pubblico espone Date, ETag e Retry-After.

Errori#

Gli errori API restituiscono un oggetto error. Usa error.code nella logica del programma; error.message è un testo inglese per le persone e può cambiare. Guida a risposte ed errori

HTTP	Codice	Significato e cosa fare
401	`invalid_api_key`	La credenziale Bearer è malformata, sconosciuta, scaduta o revocata. Usa una chiave attiva. Per l’accesso pubblico anonimo, rimuovi del tutto `Authorization`. Credenziali non valide non attivano automaticamente l’accesso anonimo.
403	`api_key_scope`	La chiave API non ha il permesso read o verify, oppure l’endpoint non accetta chiavi Bearer. Usa il permesso corretto. Le modifiche alle schede e la gestione delle chiavi richiedono una firma del dispositivo.
403	`api_key_suspended`	Questa chiave API è sospesa. Chiedi allo staff di ripristinarla; un’altra chiave non rimuove la sospensione dell’account.
403	`developer_suspended`	L’account API del titolare è sospeso oppure la scheda titolare non è disponibile. Controlla l’account titolare e le restrizioni dello staff. Creare un’altra chiave non aggira la sospensione.

Errori comuni delle richieste

HTTP Codice Significato e cosa fare

429

HTTP	Codice	Significato e cosa fare
429	`rate_limited`	È stato superato un limite anonimo, delle richieste firmate o della chiave API. Attendi almeno i secondi indicati da `Retry-After`. Condividi coda e budget dei tentativi tra i tuoi processi.
500	`internal_error`	Si è verificato un errore imprevisto del server. I dettagli interni non vengono restituiti. Riprova le letture con attese crescenti e un limite. Controlla l’esito delle scritture prima di inviare una nuova operazione firmata.
503	`busy`	L’applicazione ha raggiunto un limite temporaneo di concorrenza o del database. Attendi i secondi indicati da `Retry-After` e riprova con attese crescenti e un limite.

rate_limited

È stato superato un limite anonimo, delle richieste firmate o della chiave API.

Attendi almeno i secondi indicati da Retry-After. Condividi coda e budget dei tentativi tra i tuoi processi.

500

internal_error

Si è verificato un errore imprevisto del server. I dettagli interni non vengono restituiti.

Riprova le letture con attese crescenti e un limite. Controlla l’esito delle scritture prima di inviare una nuova operazione firmata.

503

busy

L’applicazione ha raggiunto un limite temporaneo di concorrenza o del database.

Attendi i secondi indicati da Retry-After e riprova con attese crescenti e un limite.

Leggi questa voce in JSON