Errori e limiti dell'API

Quando una richiesta alla API pubblica non va a buon fine, la risposta ha sempre lo stesso formato. Questa guida spiega come leggerla, cosa significa ogni codice e quali limiti valgono. Per l'uso generale della API vedi Usare l'API pubblica.

Il formato degli errori

Ogni errore è un oggetto JSON di questo tipo:

{
  "error": {
    "status": 422,
    "message": "Dati non validi",
    "code": "invalid_fields",
    "details": [
      { "field": "status_reason", "message": "..." }
    ]
  }
}

• status — il codice HTTP;
• message — una frase in italiano pensata per le persone: può cambiare, quindi non usarla nel codice della tua integrazione;
• code — il codice stabile dell'errore, presente sulle operazioni di scrittura e sul rifiuto per API non disponibile: è quello su cui basare la logica;
• details — l'elenco dei campi non validi, nelle risposte 422;
• existing_id o existing_contract_id — la risorsa già esistente che ha causato un 409;
• reason — il motivo di un 402.

I codici di stato

• 400 — richiesta non valida: body JSON non leggibile (invalid_json), body multipart non valido (invalid_multipart), file mancante o vuoto (file_missing), parametri di paginazione o date non validi, oppure nessun campo da aggiornare.
• 401 — "API key mancante o malformata" oppure "API key non valida o revocata": controlla l'header Authorization: Bearer <chiave> e che la chiave non sia stata revocata.
• 402 — l'operazione non è consentita dal piano: API non disponibile per l'organizzazione (feature_disabled), abbonamento non attivo, oppure quota esaurita (plan_limit). Vedi L'API non è disponibile per la mia organizzazione.
• 403 — "Scope mancante: …": la chiave non ha lo scope richiesto. Il messaggio usa il nome tecnico: read:counterparties è «Leggi controparti», read:contracts «Leggi contratti», read:milestones «Leggi scadenze», read:export «Export CSV», write:counterparties «Crea/modifica controparti», write:contracts «Crea contratti», webhooks:manage «Gestisci webhook».
• 404 — risorsa o percorso inesistente, per esempio "Rotta sconosciuta (base: /v1)", "Contratto non trovato" o "Controparte non trovata".
• 405 — metodo non supportato su quel percorso, per esempio "Scrittura non supportata su questa risorsa".
• 409 — conflitto: controparte con la stessa P.IVA/CF già esistente (duplicate_counterparty), documento identico già in archivio (duplicate_file), identificativo esterno già usato (external_id_in_use), contratto bloccato dalla firma (contract_status_locked_by_signature) o in attesa di approvazione (approval_pending).
• 413 — "Body troppo grande" (body_too_large) per un body JSON oltre 1 MB, oppure file oltre 20 MB (file_too_large).
• 415 — formato del file non supportato (unsupported_file_type): sono ammessi PDF, DOCX e TXT.
• 422 — dati non validi (invalid_fields, con details) oppure controparte indicata inesistente (counterparty_not_found).
• 429 — troppe richieste: "Rate limit superato" oltre le 60 richieste al minuto per chiave, oppure "Troppi tentativi di autenticazione falliti" quando dallo stesso client arrivano più di 30 richieste con chiave sbagliata in un minuto. Aspetta i secondi indicati nell'header Retry-After prima di riprovare.
• 500 — errore interno (internal_error) o archiviazione del documento non riuscita (storage_failed): riprova più tardi; se si ripete, contatta l'assistenza.

I limiti

• 60 richieste al minuto per ogni chiave.
• Liste: limit da 1 a 100 elementi per pagina (25 se non lo indichi).
• Export CSV: fino a 10.000 righe per file.
• Body JSON: fino a 1 MB. Documenti caricati: fino a 20 MB, in PDF, DOCX o TXT.
• Chiavi API: al massimo 20 chiavi attive per organizzazione.
• Webhook: al massimo 20 webhook attivi per organizzazione, creati dall'app o via API.
• Quote del piano: ogni contratto creato via API consuma un'unità «Contratto in ingresso», come un caricamento dall'app.

Sicurezza della chiave

La API accetta richieste da qualunque sito web (CORS aperto), perché ad autenticarle è solo la chiave. Per questo la chiave non va mai inserita nel codice di una pagina web pubblica o di un'app distribuita ai clienti: chiunque la leggerebbe. Usala solo da un server o da uno strumento di automazione. Se una chiave è stata esposta, revocala subito: vedi Le chiavi API.

Problemi comuni

• La mia integrazione si rompe quando cambia un messaggio — basa la logica sul campo code, non su message.
• Ricevo 429 anche con poche richieste — controlla che la chiave sia corretta: le richieste con chiave sbagliata contano per il limite dei tentativi falliti.
• Ricevo 402 su ogni chiamata — vedi L'API non è disponibile per la mia organizzazione.