Limiti & fair use

I limiti esistono per mantenere l’API in salute per tutti — l’uso normale non li tocca mai.

Rate limit

• Traffico dell’API pubblica: 60 richieste/minuto per client+utente come impostazione predefinita.
• In più valgono limiti infrastrutturali per IP — le integrazioni normali non li raggiungono mai.
• Colpire un limite risponde 429 con un header Retry-After; gli header X-Rate-Limit-* ti dicono in ogni momento a che punto sei.

Fair use

Oltre ai limiti rigidi al minuto c’è una guida mensile morbida: 3.000 richieste/mese (leggi il valore attuale in tempo reale da GET /v3/users/me/usage come fairUse.monthlyReference). È un indicatore, non una sanzione: superarla cambia un colore sulla tua pagina di utilizzo su my.pon.app, nient’altro. Anche i tuoi numeri in tempo reale (oggi, mese, per token) sono lì.

Quote sulle risorse

Tetti generosi contro l’automazione fuori controllo (422 QUOTA_EXCEEDED con details.resource e details.limit):

La busta degli errori

Ogni errore, ogni endpoint, la stessa forma:

{ "errors": [ { "code": "LIST_FULL", "message": "…", "details": { "limit": 5000 } } ] }

Le risposte riuscite sono sempre { "data": …, "meta": … }. I percorsi di scrittura sono amichevoli con l’idempotenza — ritentare una scrittura fallita è sicuro.