Blu Pantheon
Справочник API

Errori

Envelope di errore, mappa degli status HTTP, catalogo completo dei codici e uso del traceId con il supporto.

Tutte le risposte di errore delle API di Blu Pantheon condividono lo stesso formato, indipendentemente dal servizio e dallo status HTTP. Il campo code è l'unico valore su cui basare la logica applicativa: title e message sono destinati alle persone e possono cambiare senza preavviso.

Envelope di errore

401 Unauthorized
{
  "code": "INVALID_CREDENTIALS",
  "title": "Credenziali non valide",
  "message": "Email o password non corretti. Dopo 5 tentativi falliti l'account viene bloccato temporaneamente.",
  "traceId": "01J8ZQ3K5V6X7Y8Z9A0B1C2D3E",
  "details": []
}

Campi dell'envelope

ParametroTipoObblig.DefaultDescrizione
codestringSì—Codice stabile in MAIUSCOLO_CON_UNDERSCORE. È il solo campo su cui costruire logica applicativa e messaggi tradotti lato client.
titlestringSì—Titolo breve leggibile, adatto a essere mostrato come intestazione di un avviso. Localizzato in base all’header Accept-Language.
messagestringSì—Descrizione estesa del problema e, quando possibile, dell’azione correttiva. Non parsarla: il testo può cambiare.
traceIdstringSì—Identificativo univoco della richiesta in formato ULID. Da citare sempre nelle segnalazioni al supporto.
detailsobject[]No[]Elenco di errori puntuali. Valorizzato soprattutto per gli errori di validazione e di permessi mancanti.
details[].fieldstringNo—Percorso del campo che ha causato l’errore, con notazione a punti per gli oggetti annidati.
details[].codestringNo—Codice specifico della singola violazione, ad esempio REQUIRED o TOO_SHORT.
details[].messagestringNo—Descrizione della singola violazione, adatta a essere mostrata accanto al campo di un modulo.

Non basare la logica sui messaggi

Controllare message con confronti di stringa rende l'integrazione fragile: i testi sono localizzati e vengono riformulati nel tempo. Usa sempre code e, per la validazione, details[].code.

Mappa degli status HTTP

StatusSignificatoRitentabile
400 Bad RequestRichiesta malformata o parametri non validiNo, correggi la richiesta
401 UnauthorizedCredenziale assente, scaduta o non validaDopo aver rinnovato la credenziale
402 Payment RequiredAbbonamento sospeso o pagamento non riuscitoDopo la regolarizzazione
403 ForbiddenCredenziale valida ma priva dei permessi necessariNo, servono permessi diversi
404 Not FoundRisorsa inesistente o non visibile al tenant correnteNo
405 Method Not AllowedMetodo HTTP non supportato sul pathNo
409 ConflictConflitto con lo stato attuale della risorsaSolo dopo aver risolto il conflitto
410 GoneEndpoint dismesso dopo la data indicata in SunsetNo, migra alla nuova versione
413 Payload Too LargeBody o file oltre la dimensione massima consentitaNo
415 Unsupported Media TypeContent-Type non supportatoNo
422 Unprocessable EntitySintassi corretta ma regola di business violataNo
423 LockedRisorsa o account temporaneamente bloccatoDopo la scadenza del blocco
429 Too Many RequestsLimite di chiamate superatoSì, rispettando Retry-After
500 Internal Server ErrorErrore non previsto lato piattaformaSì, con backoff
502 Bad GatewayErrore di un servizio a monteSì, con backoff
503 Service UnavailableServizio temporaneamente non disponibile o in manutenzioneSì, con backoff
504 Gateway TimeoutTimeout di un servizio a monteSì, con backoff, verificando prima l'idempotenza

Catalogo dei codici

Autenticazione

CodiceStatusSignificatoRimedio
INVALID_CREDENTIALS401Email o password non correttiVerifica le credenziali; non distinguere il motivo nell'interfaccia
TOKEN_EXPIRED401Access token scadutoEsegui il refresh e ritenta una sola volta
TOKEN_INVALID401Token malformato o firma non verificabileRifai il login; controlla di non troncare il token
REFRESH_TOKEN_REUSED401Refresh token già utilizzatoTutte le sessioni sono state revocate: richiedi un nuovo login
MISSING_AUTHORIZATION_HEADER401Header Authorization assenteAggiungi l'header; verifica i redirect del client HTTP
INVALID_TOKEN_FORMAT401Valore non nel formato Bearer <token>Applica un trim e rimuovi prefissi duplicati
MFA_REQUIRED401Autenticazione a più fattori necessariaCompleta la sfida su /auth/mfa/verify
MFA_CODE_INVALID401Codice a più fattori erratoRichiedi un nuovo codice; attenzione al drift dell'orologio TOTP
MFA_TOKEN_EXPIRED401mfaToken scaduto dopo 5 minutiRipeti il login dall'inizio
ACCOUNT_LOCKED423Account bloccato per troppi tentativi fallitiAttendi la scadenza del blocco o contatta un amministratore
ACCOUNT_DISABLED403Utente disattivato dall'amministratoreRichiedi la riattivazione
API_KEY_REVOKED401Chiave API revocataGenera una nuova chiave e aggiorna il secret manager
API_KEY_EXPIRED401Chiave API a termine scadutaGenera una nuova chiave
SIGNATURE_MISMATCH401Firma HMAC non corrispondenteVerifica stringa canonica, body non riserializzato e segreto
TIMESTAMP_SKEW401Timestamp fuori dalla tolleranza di 300 secondiSincronizza l'orologio del server via NTP
TENANT_SELECTION_REQUIRED409L'utente appartiene a più tenantRipeti il login indicando tenantSlug

Autorizzazione

CodiceStatusSignificatoRimedio
FORBIDDEN403Operazione non consentita nel contesto correnteVerifica ruolo e ambito della credenziale
INSUFFICIENT_PERMISSIONS403Mancano permessi specificiAggiungi gli scope elencati in details al ruolo o alla chiave
TENANT_MISMATCH403La risorsa appartiene a un altro tenantUsa una credenziale del tenant corretto
SCOPE_NOT_GRANTED403Lo scope richiesto non è stato assegnato alla chiave APIRigenera la chiave con gli scope necessari
IP_NOT_ALLOWED403Indirizzo IP fuori dalla allowlist del tenantAggiungi l'IP di uscita nella configurazione di sicurezza

Validazione

CodiceStatusSignificatoRimedio
VALIDATION_ERROR400Uno o più campi non superano la validazioneCorreggi i campi elencati in details
INVALID_EMAIL400Formato dell'indirizzo email non validoNormalizza e valida l'indirizzo prima dell'invio
INVALID_PHONE_NUMBER400Numero di telefono non valido in formato E.164Usa il formato internazionale con prefisso
PASSWORD_TOO_WEAK400Password non conforme ai criteri del tenantApplica i requisiti minimi indicati in details
INVALID_CURSOR400Cursore scaduto, malformato o incoerente con i filtriRiparti dalla prima pagina
INVALID_DATE_RANGE400Intervallo temporale incoerente o troppo ampioRiduci la finestra richiesta
UNSUPPORTED_FILE_TYPE415Tipo di file non ammesso per l'uploadConverti il file in un formato supportato
FILE_TOO_LARGE413File oltre la dimensione massimaRiduci o suddividi il file
MISSING_REQUIRED_FIELD400Campo obbligatorio assente dal bodyAggiungi il campo indicato in details

Risorse

CodiceStatusSignificatoRimedio
USER_NOT_FOUND404Utente inesistente o non visibileVerifica l'identificativo e il tenant della credenziale
TENANT_NOT_FOUND404Tenant inesistenteVerifica lo slug o l'identificativo
PROJECT_NOT_FOUND404Progetto inesistenteVerifica projectId
SESSION_NOT_FOUND404Sessione inesistente o già archiviataVerifica l'identificativo e la finestra di conservazione
CLIENT_NOT_FOUND404Cliente inesistenteVerifica clientId
DATA_STORE_NOT_FOUND404Knowledge base inesistenteVerifica storeId
DOCUMENT_NOT_FOUND404Documento inesistente o eliminatoRicarica l'elenco dei documenti
BOOKING_NOT_FOUND404Prenotazione inesistente o annullataVerifica bookingId
INVOICE_NOT_FOUND404Fattura inesistenteVerifica l'identificativo del documento
API_KEY_NOT_FOUND404Chiave API inesistenteRicarica l'elenco delle chiavi dalla Console

Conflitti e stato

CodiceStatusSignificatoRimedio
EMAIL_ALREADY_EXISTS409Esiste già un utente con quell'email nel tenantRecupera l'utente esistente o usa un altro indirizzo
DUPLICATE_REQUEST409Idempotency-Key già usata con un body diversoGenera una nuova chiave per una richiesta diversa
RESOURCE_CONFLICT409Modifica concorrente sulla stessa risorsaRileggi la risorsa e ritenta l'operazione
SESSION_ALREADY_CLOSED409La sessione è già stata chiusaNessuna azione necessaria
BOOKING_SLOT_UNAVAILABLE409Lo slot è stato occupato nel frattempoRileggi la disponibilità e proponi un nuovo orario
INVALID_STATE_TRANSITION422Transizione di stato non ammessaVerifica lo stato corrente prima dell'operazione
HANDOVER_ALREADY_ACTIVE409Un passaggio a operatore è già in corsoRiprendi la conversazione esistente

Limiti e quote

CodiceStatusSignificatoRimedio
RATE_LIMITED429Limite di chiamate superatoAttendi i secondi indicati in Retry-After
QUOTA_EXCEEDED429Quota mensile del piano esauritaAttendi il rinnovo del ciclo o aumenta il piano
PLAN_LIMIT_REACHED403Limite strutturale del piano raggiunto (utenti, progetti, storage)Aggiorna il piano o libera risorse
CONCURRENCY_LIMIT429Troppe richieste contemporanee dalla stessa credenzialeRiduci il parallelismo
STORAGE_LIMIT_REACHED403Spazio della knowledge base esauritoElimina documenti o aumenta lo spazio

Fatturazione

CodiceStatusSignificatoRimedio
PAYMENT_REQUIRED402Pagamento non riuscito, servizio limitatoAggiorna il metodo di pagamento nella Console
SUBSCRIPTION_INACTIVE402Abbonamento sospeso, scaduto o annullatoRiattiva l'abbonamento
TRIAL_EXPIRED402Periodo di prova terminatoAttiva un piano a pagamento
INVALID_BILLING_PROFILE422Dati di fatturazione incompleti o non validiCompleta partita IVA, codice SDI o PEC
PAYMENT_METHOD_DECLINED402Metodo di pagamento rifiutato dall'emittenteUsa un altro metodo di pagamento

Sistema

CodiceStatusSignificatoRimedio
INTERNAL_ERROR500Errore non previsto lato piattaformaRitenta con backoff; se persiste segnala il traceId
SERVICE_UNAVAILABLE503Servizio temporaneamente non disponibileRitenta con backoff; se persiste apri una richiesta
UPSTREAM_TIMEOUT504Timeout di un servizio a monteRitenta con backoff verificando l'idempotenza
MAINTENANCE_MODE503Manutenzione pianificata in corsoAttendi la fine della finestra comunicata
ENDPOINT_REMOVED410Endpoint dismessoMigra alla versione indicata nella documentazione
FEATURE_NOT_ENABLED403Funzionalità non abilitata per il tenantRichiedi l'attivazione al tuo referente commerciale

Il catalogo esteso con le note operative per gli amministratori è disponibile in Codici di errore.

Errori di validazione

Quando code vale VALIDATION_ERROR, l'array details contiene una voce per ogni campo non valido. È il formato pensato per essere mappato direttamente sui campi di un modulo.

400 Bad Request
{
  "code": "VALIDATION_ERROR",
  "title": "Dati non validi",
  "message": "La richiesta contiene 3 campi non validi.",
  "traceId": "01J8ZQ3K5V6X7Y8Z9A0B1C2D3E",
  "details": [
    {
      "field": "email",
      "code": "INVALID_FORMAT",
      "message": "Indirizzo email non valido."
    },
    {
      "field": "password",
      "code": "TOO_SHORT",
      "message": "La password deve contenere almeno 12 caratteri."
    },
    {
      "field": "profile.phoneNumber",
      "code": "INVALID_FORMAT",
      "message": "Il numero deve essere in formato E.164, ad esempio +390212345678."
    }
  ]
}

Gestione lato client:

handle-validation.ts
interface ApiError {
  code: string;
  title: string;
  message: string;
  traceId: string;
  details?: { field?: string; code?: string; message?: string }[];
}

export function toFieldErrors(error: ApiError): Record<string, string> {
  if (error.code !== 'VALIDATION_ERROR') return {};

  return Object.fromEntries(
    (error.details ?? [])
      .filter((d) => Boolean(d.field))
      .map((d) => [d.field as string, d.message ?? 'Valore non valido']),
  );
}

Codici di dettaglio ricorrenti

I valori più frequenti di details[].code sono REQUIRED, INVALID_FORMAT, TOO_SHORT, TOO_LONG, OUT_OF_RANGE, NOT_UNIQUE e UNSUPPORTED_VALUE. Sono stabili e possono essere usati per generare messaggi tradotti nella lingua della tua applicazione.

Il traceId

Ogni richiesta riceve un traceId in formato ULID, presente sia nell'envelope di errore sia nell'header X-BP-Trace-Id di tutte le risposte, anche quelle di successo.

Header sempre presente
X-BP-Trace-Id: 01J8ZQ3K5V6X7Y8Z9A0B1C2D3E

Registralo sempre

Includi il traceId in ogni riga di log relativa a una chiamata API, sia in caso di successo sia in caso di errore. Senza di esso una segnalazione richiede molto più tempo per essere analizzata.

Non mostrarlo ai clienti finali

Il traceId è un dato di diagnostica destinato agli sviluppatori. In un'interfaccia rivolta agli utenti finali mostra un messaggio comprensibile e riporta il codice solo in un'area tecnica o in un tooltip.

Citalo nelle segnalazioni

Quando apri una richiesta al supporto indica: traceId, code, timestamp UTC della chiamata, metodo e path, ambiente e identificativo della credenziale usata (solo il prefisso, mai il segreto).

ConsoleSupportoRichiesteNuova richiesta

Non inviare mai credenziali al supporto

Nelle segnalazioni non allegare chiavi API complete, token, password o segreti HMAC. Il prefisso della chiave (bp_live_xxxx) e il traceId sono sufficienti per identificare la richiesta.

Il traceId viene conservato nei log della piattaforma per 30 giorni: segnala gli incidenti entro questa finestra per consentire l'analisi puntuale della richiesta.

На этой странице