Errori & Rate Limit

Come gestire gli errori API e i limiti di frequenza.

Formato errore

In caso di errore, la risposta conterrà un campo error con la descrizione del problema:

Response — Errore

{
  "error": "Messaggio di errore descrittivo"
}

Codici di stato HTTP

Codice	Significato	Quando
200	OK	Richiesta completata con successo
201	Created	Risorsa creata con successo (POST)
400	Bad Request	Parametri mancanti, formato errato o validazione fallita
401	Unauthorized	API key mancante, non valida o disattivata
403	Forbidden	Piano attuale non consente questa operazione (es. Free → no API)
404	Not Found	Risorsa non trovata con l'ID specificato
405	Method Not Allowed	Metodo HTTP non supportato per questo endpoint
429	Too Many Requests	Superato il rate limit (100 richieste/minuto)
500	Internal Server Error	Errore interno del server — riprova o contattaci

Errori comuni

Missing or invalid API key

Causa: L'header Authorization manca o la chiave non è nel formato corretto.

Soluzione: Assicurati di inviare l'header: Authorization: Bearer fir_xxx

API key not found or disabled

Causa: La chiave API è stata revocata o non esiste.

Soluzione: Genera una nuova chiave da Impostazioni → API Keys.

API access not available on your plan

Causa: Il piano Free non include l'accesso API.

Soluzione: Passa al piano Starter (lettura) o Pro/Business (completo).

Email already exists

Causa: Un contatto con la stessa email esiste già nell'organizzazione.

Soluzione: Usa un'email diversa o aggiorna il contatto esistente con PUT.

Invalid email format

Causa: L'email fornita non è in un formato valido.

Soluzione: Verifica il formato dell'email (es. nome@dominio.com).

Rate Limiting

Le API supportano un massimo di 100 richieste al minuto per API key.

Header di risposta

Ogni risposta include header per monitorare il tuo utilizzo:

Header	Descrizione
`X-RateLimit-Limit`	Numero massimo di richieste per finestra (100)
`X-RateLimit-Remaining`	Richieste rimanenti nella finestra corrente
`X-RateLimit-Reset`	Timestamp Unix quando il contatore si resetta

429 Too Many Requests: Se superi il limite, attendi che la finestra si resetti prima di riprovare. Implementa un backoff esponenziale nelle tue integrazioni.

Best Practice

Usa la paginazione: non richiedere tutti i dati in una sola chiamata. Usa limit e offset.

Gestisci gli errori: controlla sempre il codice HTTP e il campo error nella risposta.

Implementa retry con backoff: per errori 429 e 5xx, riprova con attese crescenti.

Conserva le API key in sicurezza: non includerle nel codice frontend o nei repository pubblici.

Usa i filtri: quando possibile, filtra lato server per ridurre il volume di dati trasferiti.

Monitora i rate limit: controlla gli header X-RateLimit per evitare di superare i limiti.