Codici di errore

Tabella consolidata dei codici di errore di Blu Pantheon con stato HTTP, causa e azione correttiva, e uso di traceId e X-BP-Delivery.

Ogni errore restituito dalla piattaforma ha un codice stabile, uno stato HTTP e un messaggio leggibile. Il codice è la parte su cui costruire la logica applicativa: il messaggio può cambiare nel tempo e con la lingua, il codice no.

Struttura della risposta di errore

Formato standard di errore

{
  "error": {
    "code": "VALIDATION_FAILED",
    "title": "Dati non validi",
    "message": "Uno o piu campi della richiesta non sono validi.",
    "details": [
      { "field": "email", "code": "INVALID_FORMAT", "message": "Formato email non valido." },
      { "field": "phone", "code": "REQUIRED", "message": "Campo obbligatorio." }
    ],
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "timestamp": "2026-09-04T10:22:41.318Z",
    "documentation": "https://docs.blupantheon.com/it/docs/supporto/codici-errore"
  }
}

Campi dell’oggetto error

Parametro	Tipo	Obblig.	Default	Descrizione
`code`	`string`	Sì	—	Codice stabile dell’errore. Usa questo valore nella logica applicativa.
`title`	`string`	Sì	—	Titolo breve, adatto a essere mostrato all’utente.
`message`	`string`	Sì	—	Descrizione leggibile. Può variare fra le versioni e le lingue.
`details`	`array`	No	—	Elenco degli errori di validazione per singolo campo.
`traceId`	`string`	Sì	—	Correlatore della richiesta. Comunicalo sempre al supporto.
`timestamp`	`string`	Sì	—	Momento in cui l’errore si è verificato, in UTC.
`documentation`	`string`	No	—	Collegamento alla pagina di riferimento.

Autenticazione

Codice	HTTP	Messaggio	Causa	Cosa fare
`UNAUTHENTICATED`	401	Autenticazione richiesta	Header `Authorization` assente	Aggiungi l'header con il token o la chiave API
`INVALID_CREDENTIALS`	401	Credenziali non valide	Email o password errate	Verifica le credenziali; dopo 5 tentativi l'utenza si blocca
`TOKEN_EXPIRED`	401	Token scaduto	Il token di accesso ha superato la validità	Rinnova il token con il token di aggiornamento
`TOKEN_INVALID`	401	Token non valido	Token malformato, alterato o firmato con chiave ritirata	Esegui di nuovo l'autenticazione
`TOKEN_REVOKED`	401	Token revocato	Sessione terminata o password modificata	Esegui di nuovo l'autenticazione
`API_KEY_INVALID`	401	Chiave API non valida	Chiave inesistente o errata	Verifica la chiave; se persa, revocala e creane una nuova
`API_KEY_EXPIRED`	401	Chiave API scaduta	Superata la data di scadenza	Crea una nuova chiave e aggiorna le integrazioni
`API_KEY_REVOKED`	401	Chiave API revocata	Revocata manualmente	Crea una nuova chiave
`MFA_REQUIRED`	401	Verifica a due fattori richiesta	Credenziali corrette, secondo fattore mancante	Invia il codice MFA all'endpoint di verifica
`MFA_INVALID`	401	Codice di verifica non valido	Codice errato o scaduto	Sincronizza l'orologio del dispositivo e riprova
`ACCOUNT_LOCKED`	423	Account bloccato	Troppi tentativi falliti	Attendi 15 minuti o chiedi lo sblocco a un amministratore
`ACCOUNT_DISABLED`	403	Account disattivato	Utenza disattivata da un amministratore	Contatta un amministratore del tenant
`SSO_REQUIRED`	403	Accesso federato obbligatorio	Enforcement SSO attivo sul dominio	Accedi tramite l'identity provider aziendale
`SSO_CONFIG_ERROR`	500	Configurazione SSO non valida	Metadati o certificato non validi	Verifica la configurazione SSO

Autorizzazione

Codice	HTTP	Messaggio	Causa	Cosa fare
`FORBIDDEN`	403	Accesso negato	Permesso mancante per l'operazione	Verifica i ruoli in Profilo, I miei permessi
`INSUFFICIENT_PERMISSIONS`	403	Permessi insufficienti	Manca un permesso specifico, formato `{servizio}:{risorsa}:{azione}`	Chiedi a un amministratore di aggiornare il ruolo
`TENANT_MISMATCH`	403	Tenant non corrispondente	La risorsa appartiene a un altro tenant	Verifica il tenant selezionato e il token in uso
`SCOPE_NOT_GRANTED`	403	Ambito non concesso	La chiave API non ha l'ambito richiesto	Crea una chiave con gli ambiti necessari
`RESOURCE_LOCKED`	423	Risorsa bloccata	Un altro utente la sta modificando	Attendi e riprova
`DATA_RESTRICTED`	403	Trattamento limitato	Il contatto è soggetto a limitazione ex art. 18 GDPR	Rimuovi la limitazione se non più necessaria

Validazione

Codice	HTTP	Messaggio	Causa	Cosa fare
`VALIDATION_FAILED`	422	Dati non validi	Uno o più campi non superano la validazione	Leggi l'array `details` per il dettaglio per campo
`REQUIRED_FIELD_MISSING`	422	Campo obbligatorio mancante	Un campo richiesto è assente o vuoto	Aggiungi il campo indicato
`INVALID_FORMAT`	422	Formato non valido	Il valore non rispetta il formato atteso	Correggi il formato, es. email o data ISO 8601
`INVALID_ENUM_VALUE`	422	Valore non ammesso	Valore fuori dall'insieme consentito	Usa uno dei valori elencati nel messaggio
`VALUE_OUT_OF_RANGE`	422	Valore fuori intervallo	Numero o data oltre i limiti ammessi	Rientra nell'intervallo indicato
`STRING_TOO_LONG`	422	Testo troppo lungo	Superata la lunghezza massima	Riduci la lunghezza del testo
`INVALID_JSON`	400	Corpo della richiesta non valido	JSON malformato	Verifica la sintassi del payload
`UNSUPPORTED_MEDIA_TYPE`	415	Tipo di contenuto non supportato	Header `Content-Type` errato	Imposta `application/json`
`INVALID_VAT_NUMBER`	422	Partita IVA non valida	Formato o cifra di controllo errati	Usa il formato con prefisso, es. `IT01234567890`
`INVALID_TAX_CODE`	422	Codice Fiscale non valido	Lunghezza o caratteri non validi	16 caratteri per persone fisiche, 11 cifre per persone giuridiche
`INVALID_SDI_CODE`	422	Codice Destinatario non valido	Lunghezza diversa da 7 caratteri	Inserisci 7 caratteri alfanumerici, es. `ABC1234`
`INVALID_PHONE_NUMBER`	422	Numero di telefono non valido	Formato non conforme a E.164	Usa il formato internazionale, es. `+393401234567`

Risorse

Codice	HTTP	Messaggio	Causa	Cosa fare
`NOT_FOUND`	404	Risorsa non trovata	Identificativo inesistente o già eliminato	Verifica l'identificativo
`ENDPOINT_NOT_FOUND`	404	Endpoint inesistente	Percorso o versione errati	Consulta la specifica OpenAPI
`METHOD_NOT_ALLOWED`	405	Metodo non consentito	Verbo HTTP errato per il percorso	Usa il verbo indicato nella documentazione
`PROJECT_NOT_FOUND`	404	Progetto non trovato	Progetto eliminato o chiave errata	Verifica il progetto in Console
`PROJECT_NOT_PUBLISHED`	409	Progetto non pubblicato	Il progetto è in bozza	Pubblica il progetto
`DOCUMENT_NOT_INDEXED`	409	Documento non indicizzato	Indicizzazione in corso o fallita	Attendi il completamento o correggi l'errore
`SESSION_NOT_FOUND`	404	Sessione non trovata	Sessione scaduta o eliminata per retention	Verifica i tempi di conservazione configurati
`CONTACT_NOT_FOUND`	404	Contatto non trovato	Identificativo errato o contatto cancellato	Verifica l'identificativo o la chiave esterna

Conflitti

Codice	HTTP	Messaggio	Causa	Cosa fare
`CONFLICT`	409	Conflitto sullo stato della risorsa	Operazione incompatibile con lo stato attuale	Rileggi la risorsa e riprova
`ALREADY_EXISTS`	409	Risorsa già esistente	Violazione di un vincolo di unicità	Aggiorna la risorsa esistente invece di crearla
`EMAIL_ALREADY_REGISTERED`	409	Email già registrata	Un'utenza con questa email esiste già nel tenant	Usa un altro indirizzo o riattiva l'utenza esistente
`SLOT_NO_LONGER_AVAILABLE`	409	Slot non più disponibile	Occupato da un altro canale nel frattempo	Proponi le alternative restituite nella risposta
`BOOKING_ALREADY_CANCELLED`	409	Prenotazione già annullata	Disdetta già registrata	Nessuna azione necessaria
`CONCURRENT_MODIFICATION`	409	Modifica concorrente	La risorsa è cambiata dopo la lettura	Rileggi, riapplica le modifiche e riprova
`WEBHOOK_URL_DUPLICATE`	409	Endpoint già registrato	Stesso URL già presente	Modifica l'endpoint esistente
`IDEMPOTENCY_KEY_REUSED`	409	Chiave di idempotenza riutilizzata	Stessa chiave con payload diverso	Usa una chiave nuova per una richiesta diversa

Limiti e quote

Codice	HTTP	Messaggio	Causa	Cosa fare
`RATE_LIMIT_EXCEEDED`	429	Troppe richieste	Superato il limite di frequenza	Attendi il tempo indicato in `Retry-After`
`QUOTA_EXCEEDED`	429	Quota del piano esaurita	Consumo oltre il limite del piano	Aumenta il piano o attendi il rinnovo del periodo
`CONCURRENT_LIMIT_EXCEEDED`	429	Troppe richieste simultanee	Superato il numero di richieste parallele	Riduci il parallelismo del client
`PAYLOAD_TOO_LARGE`	413	Payload troppo grande	Corpo della richiesta oltre il limite	Riduci le dimensioni o usa il caricamento a blocchi
`FILE_TOO_LARGE`	413	File troppo grande	Documento oltre la dimensione massima	Suddividi il documento
`TOO_MANY_DOCUMENTS`	429	Troppi documenti	Limite di documenti della knowledge base raggiunto	Elimina i documenti obsoleti o aumenta il piano
`MESSAGE_LIMIT_EXCEEDED`	429	Limite di messaggi raggiunto	Quota mensile di conversazioni esaurita	Verifica i consumi in Amministrazione, Fatturazione

Fatturazione

Codice	HTTP	Messaggio	Causa	Cosa fare
`BILLING_DETAILS_INCOMPLETE`	422	Dati di fatturazione incompleti	Manca un campo fiscale obbligatorio	Completa i dati in Amministrazione, Fatturazione
`BILLING_ACCOUNT_SUSPENDED`	402	Account sospeso	Fatture insolute oltre i termini	Regolarizza la posizione e contatta l'amministrazione
`PLAN_LIMIT_REACHED`	402	Limite del piano raggiunto	La funzione richiede un piano superiore	Aggiorna il piano
`INVOICE_NOT_AVAILABLE`	404	Fattura non disponibile	Documento non ancora emesso	Attendi l'emissione, prevista a inizio mese
`SDI_REJECTED`	422	Fattura scartata dallo SDI	Errore formale nei dati fiscali	Correggi i dati; la riemissione è automatica entro 24 ore
`VIES_VALIDATION_FAILED`	422	Numero IVA non validato dal VIES	Numero non iscritto agli archivi VIES	Richiedi l'iscrizione all'autorità fiscale del tuo Paese

Integrazioni e webhook

Codice	HTTP	Messaggio	Causa	Cosa fare
`WEBHOOK_DELIVERY_FAILED`	—	Consegna del webhook fallita	Endpoint irraggiungibile o in errore	Vedi Webhook non ricevuti
`WEBHOOK_SIGNATURE_INVALID`	401	Firma non valida	Firma calcolata sul corpo deserializzato	Usa il corpo grezzo della richiesta
`WEBHOOK_ENDPOINT_SUSPENDED`	409	Endpoint sospeso	Troppi fallimenti consecutivi	Correggi la causa e riattiva l'endpoint
`WEBHOOK_TIMEOUT`	—	Timeout di consegna	Nessuna risposta entro 10 secondi	Rendi asincrona l'elaborazione
`TOOL_EXECUTION_FAILED`	502	Esecuzione dello strumento fallita	Il sistema esterno ha restituito un errore	Verifica i log del tuo sistema
`TOOL_TIMEOUT`	504	Timeout dello strumento	Risposta oltre il tempo massimo	Ottimizza il tuo endpoint o aumenta il timeout consentito
`DOMAIN_NOT_ALLOWED`	403	Dominio non autorizzato	Il widget è caricato da un dominio non in elenco	Aggiungi il dominio ai domini autorizzati
`WHATSAPP_WINDOW_CLOSED`	409	Finestra di servizio chiusa	Oltre 24 ore dall'ultimo messaggio dell'utente	Usa un template approvato
`WHATSAPP_TEMPLATE_NOT_APPROVED`	409	Template non approvato	Template in revisione o rifiutato da Meta	Attendi l'approvazione o correggi il contenuto
`SMTP_CONNECTION_FAILED`	502	Connessione SMTP fallita	Host, porta o credenziali errati	Verifica la configurazione SMTP
`EMAIL_ADDRESS_SUPPRESSED`	409	Indirizzo sospeso	Bounce definitivo o segnalazione di spam	Verifica l'indirizzo e riabilitalo se corretto
`EXTERNAL_SERVICE_UNAVAILABLE`	503	Servizio esterno non disponibile	Il sistema integrato non risponde	Riprova più tardi, verifica lo stato del fornitore

Sistema

Codice	HTTP	Messaggio	Causa	Cosa fare
`INTERNAL_ERROR`	500	Errore interno	Anomalia della piattaforma	Riprova; se persiste apri una richiesta con il `traceId`
`SERVICE_UNAVAILABLE`	503	Servizio temporaneamente non disponibile	Manutenzione o sovraccarico	Riprova; se persiste apri una richiesta
`GATEWAY_TIMEOUT`	504	Timeout del gateway	Elaborazione oltre il tempo massimo	Riduci la dimensione della richiesta e riprova
`MAINTENANCE_MODE`	503	Manutenzione in corso	Finestra di manutenzione pianificata	Attendi il termine indicato dall'header `Retry-After`
`MODEL_UNAVAILABLE`	503	Modello non disponibile	Il modello configurato non risponde	Verifica lo stato del servizio; è previsto un ripiego automatico
`MODEL_CONTENT_FILTERED`	422	Contenuto filtrato	Il contenuto ha attivato i filtri di sicurezza del modello	Riformula la richiesta
`INDEXING_FAILED`	500	Indicizzazione fallita	Documento illeggibile, protetto o corrotto	Rimuovi la protezione o converti il documento
`EXPORT_FAILED`	500	Esportazione fallita	Errore durante la preparazione del pacchetto	Riprova; per volumi elevati contatta il supporto

Usare il traceId

Ogni risposta della piattaforma contiene l'header X-BP-Trace-Id, riportato anche nel corpo degli errori come traceId. È il correlatore che collega fra loro tutti i passaggi interni di una richiesta.

Estrarre il traceId da una risposta

curl -sS -D - -o /dev/null \
  "https://api.blupantheon.com/console/v1/contacts" \
  -H "Authorization: Bearer $BP_TOKEN" | grep -i "x-bp-trace-id"

Registra il traceId nei tuoi log

Salva il valore insieme alla risposta di errore. Senza di esso, ricostruire l'accaduto a posteriori è molto più lento.

Cercalo nell'audit log

ConsoleAmministrazioneAudit log

Il filtro per traceId mostra tutte le voci correlate alla stessa richiesta.

Comunicalo al supporto

Con il traceId il supporto ricostruisce l'intero percorso della richiesta senza chiederti ulteriori informazioni. È la singola informazione che riduce di più i tempi di risoluzione.

Usare X-BP-Delivery

Per i problemi di consegna dei webhook, l'identificativo equivalente è X-BP-Delivery: identifica univocamente la consegna, è stabile fra i ritentativi dello stesso evento ed è ricercabile nel registro delle consegne.

ConsoleConfigurazioneWebhookEndpointConsegne

Regola pratica

Problema su una chiamata API: comunica il traceId. Problema su una consegna webhook: comunica il X-BP-Delivery. Se hai entrambi, inviali entrambi.

Gestione degli errori lato client

Strategia consigliata

401 TOKEN_EXPIRED        rinnova il token e ripeti la richiesta una sola volta
401 altri codici         non ripetere, richiede intervento sulle credenziali
403                      non ripetere, richiede modifica dei permessi
404                      non ripetere, verifica l'identificativo
409                      rileggi la risorsa, riapplica le modifiche, riprova
422                      non ripetere, correggi i dati
429                      attendi il valore di Retry-After, poi riprova
500 502 503 504          riprova con attesa crescente, massimo 3 tentativi

Non ripetere gli errori 4xx

Ad eccezione di 401 con token scaduto, 409 e 429, gli errori 4xx indicano un problema nella richiesta: ripeterla produrrà sempre lo stesso esito e consumerà quota inutilmente.