Riferimento completo di tutti i codici di errore nell'API GraphQL di Blue, organizzato per categoria
Formato della Risposta di Errore
L'API GraphQL di Blue restituisce errori in un formato standardizzato seguendo la specifica GraphQL. Quando si verifica un errore, la risposta include un array errors con informazioni dettagliate su cosa è andato storto.
Esempio di Risposta di Errore
{
"errors": [
{
"message": "Todo was not found.",
"extensions": {
"code": "TODO_NOT_FOUND"
}
}
]
}
Struttura dell'Errore
Ogni oggetto errore contiene:
- message: Una descrizione leggibile dell'errore
- extensions.code: Un codice di errore leggibile dalla macchina per la gestione programmatica
Sicurezza degli Errori in Produzione
Blue implementa un sistema di sicurezza per l'esposizione degli errori:
- Errori Sicuri: Mostra codici di errore e messaggi reali ai clienti
- Errori Non Sicuri: Restituisce
INTERNAL_SERVER_ERROR generico per nascondere dettagli sensibili
- Risorsa Non Trovata: Tutti gli errori
*_NOT_FOUND sono considerati sicuri e sempre esposti
Categorie di Errore
Blue definisce 108 codici di errore personalizzati organizzati nelle seguenti categorie:
Errori di Autenticazione e Autorizzazione
| Codice di Errore |
Messaggio |
Descrizione |
UNAUTHENTICATED |
"Autenticazione richiesta." |
La richiesta richiede autenticazione ma non è stata fornita |
FORBIDDEN |
"Non sei autorizzato." |
Autenticato ma privo delle autorizzazioni richieste |
Errori di Risorsa Non Trovata (52 totali)
Risorse Core
| Codice di Errore |
Messaggio |
Descrizione |
TODO_NOT_FOUND |
"Todo non trovato." |
Il record/todo non esiste o l'utente non ha accesso |
TODO_LIST_NOT_FOUND |
"Lista todo non trovata." |
La lista non esiste o l'utente non ha accesso |
PROJECT_NOT_FOUND |
"Progetto non trovato." |
Il progetto non esiste o l'utente non ha accesso |
COMPANY_NOT_FOUND |
"Azienda non trovata." |
L'azienda non esiste o l'utente non ha accesso |
USER_NOT_FOUND |
"Utente non trovato." |
L'utente non esiste nel sistema |
Campi e Moduli Personalizzati
| Codice di Errore |
Messaggio |
Descrizione |
CUSTOM_FIELD_NOT_FOUND |
"Campo personalizzato non trovato." |
Il campo personalizzato non esiste |
CUSTOM_FIELD_OPTION_NOT_FOUND |
"Opzione campo personalizzato non trovata." |
L'opzione del campo di selezione non esiste |
FORM_NOT_FOUND |
"Modulo non trovato." |
Il modello di modulo non esiste |
FORM_FIELD_NOT_FOUND |
"Campo del modulo non trovato." |
Il campo del modulo non esiste |
Componenti del Progetto
| Codice di Errore |
Messaggio |
Descrizione |
TAG_NOT_FOUND |
"Tag non trovato." |
Il tag non esiste nel progetto |
AUTOMATION_NOT_FOUND |
"Automazione non trovata." |
La regola di automazione non esiste |
CHART_NOT_FOUND |
"Grafico non trovato." |
Il grafico del dashboard non esiste |
WEBHOOK_NOT_FOUND |
"Webhook non trovato." |
La configurazione del webhook non esiste |
TEMPLATE_NOT_FOUND |
"Modello non trovato." |
Il modello di progetto non esiste |
| Codice di Errore |
Messaggio |
Descrizione |
COMMENT_NOT_FOUND |
"Commento non trovato." |
Il commento non esiste |
ACTIVITY_NOT_FOUND |
"Attività non trovata." |
L'entrata del registro delle attività non esiste |
REACTION_NOT_FOUND |
"Reazione non trovata." |
La reazione al commento non esiste |
Altre Risorse
| Codice di Errore |
Messaggio |
Descrizione |
FILE_NOT_FOUND |
"File non trovato." |
L'allegato del file non esiste |
SUBSCRIPTION_NOT_FOUND |
"Sottoscrizione non trovata." |
La sottoscrizione di fatturazione non esiste |
INVOICE_NOT_FOUND |
"Fattura non trovata." |
Il record della fattura non esiste |
CHECKLIST_NOT_FOUND |
"Checklist non trovata." |
La checklist non esiste |
CHECKLIST_ITEM_NOT_FOUND |
"Elemento della checklist non trovato." |
L'elemento della checklist non esiste |
PROJECT_ROLE_NOT_FOUND |
"Ruolo del progetto non trovato." |
Il ruolo personalizzato del progetto non esiste |
PROJECT_ACCESS_NOT_FOUND |
"Accesso al progetto non trovato." |
L'accesso dell'utente al progetto non esiste |
NOTIFICATION_NOT_FOUND |
"Notifica non trovata." |
La notifica non esiste |
DASHBOARD_NOT_FOUND |
"Dashboard non trovata." |
Il dashboard non esiste |
KEY_NOT_FOUND |
"Chiave non trovata." |
La chiave delle impostazioni non esiste |
Errori di Validazione
| Codice di Errore |
Messaggio |
Descrizione |
BAD_USER_INPUT |
"Input non valido." |
Fallimento della validazione dell'input generico |
VALIDATION_ERROR |
"Parametri non validi" |
I parametri della richiesta non hanno superato la validazione |
BAD_EMAIL |
"Devi inserire un'email valida." |
Formato email non valido |
INVALID_IDS |
"ID non validi." |
Uno o più ID nella richiesta non sono validi |
PHONE_INVALID |
"Telefono non valido." |
Formato numero di telefono non valido |
URL_INVALID |
"URL non valido." |
Formato URL non valido |
INVALID_RECURRING_DUE_DATE |
"Data di scadenza non valida per il compito ricorrente" |
Fallimento della validazione della data del compito ricorrente |
INVALID_COLOR |
"Colore non valido" |
Il valore del colore non corrisponde al formato previsto |
Errori di Logica Aziendale
Limiti e Quote
| Codice di Errore |
Messaggio |
Descrizione |
COMPANY_LIMIT |
"Hai raggiunto il limite di aziende per il tuo account." |
Limite massimo di aziende raggiunto |
PROJECT_LIMIT |
"Hai raggiunto il limite di progetti per la tua azienda." |
Limite massimo di progetti raggiunto |
USER_LIMIT |
"Hai raggiunto il limite di utenti per la tua azienda." |
Limite massimo di utenti raggiunto |
PROJECT_TEMPLATE_LIMIT |
"Hai raggiunto il limite di modelli per la tua azienda." |
Limite massimo di modelli raggiunto |
CUSTOM_FIELD_LIMIT |
"Limite di campi personalizzati raggiunto." |
Limite massimo di campi personalizzati raggiunto |
TODO_LIST_LIMIT |
"Hai raggiunto il limite di liste per il tuo progetto." |
Limite massimo di liste per progetto |
TOO_MANY_TODOS |
"Troppe todo." |
Limite di record superato |
TOO_MANY_OPTIONS |
"Troppe opzioni." |
Limite di opzioni del campo di selezione superato |
MAX_FILE_SIZE |
"La dimensione massima del file è 4.8gb" |
Limite di dimensione del file caricato superato |
Conflitti di Risorsa
| Codice di Errore |
Messaggio |
Descrizione |
TAG_ALREADY_EXISTS |
"Il tag esiste già." |
Esiste un tag con lo stesso nome nel progetto |
COMPANY_SLUG_ALREADY_EXISTS |
"L'azienda esiste già." |
Lo slug/URL dell'azienda è già in uso |
USER_ALREADY_EXISTS |
"L'utente esiste già." |
L'email dell'utente è già registrata |
ALREADY_INVITED |
"L'utente è già stato invitato." |
L'utente ha già un invito in sospeso |
USER_ALREADY_IN_PROJECT |
"L'utente è già in questo progetto." |
L'utente ha già accesso al progetto |
FILE_TYPE_NOT_ALLOWED |
"Tipo di file non consentito." |
Il tipo di file caricato è vietato |
Errori di Permesso e Accesso
| Codice di Errore |
Messaggio |
Descrizione |
UNABLE_TO_DELETE_ONLY_ADMIN |
"Impossibile eliminare l'unico Admin nell'azienda." |
Non è possibile rimuovere l'ultimo admin |
UNABLE_TO_UPDATE_OWNER |
"Impossibile aggiornare il PROPRIETARIO." |
Non è possibile modificare i permessi del proprietario |
TODO_LIST_IS_HIDDEN |
"La lista todo è nascosta." |
Lista nascosta dal ruolo dell'utente |
COMPANY_NOT_ACTIVE |
"L'azienda non è attiva." |
Sottoscrizione dell'azienda inattiva |
PROJECT_NOT_ACTIVE |
"Il progetto non è attivo." |
Il progetto è archiviato/inattivo |
Errori di Integrità dei Dati
| Codice di Errore |
Messaggio |
Descrizione |
UNABLE_TO_DELETE_LIST_WITH_TODOS |
"Impossibile eliminare la lista con i todo." |
La lista deve essere vuota per essere eliminata |
UNABLE_TO_DELTE_FILE |
"Impossibile eliminare il file." |
Eliminazione del file fallita (errore di battitura nel codice) |
UNABLE_TO_MOVE_TODO |
"Impossibile spostare il todo." |
Impossibile spostare il record tra le liste |
DEPENDENCY_HAS_DEPENDENCY |
"La dipendenza ha una dipendenza" |
Rilevata dipendenza circolare |
TODO_DEPENDS_ON_ITSELF |
"Il todo dipende da se stesso" |
Dipendenza auto-referenziale |
Errori di Stripe/Pagamento
| Codice di Errore |
Messaggio |
Descrizione |
STRIPE_CREATING_CUSTOMER |
"Errore durante la creazione del cliente in Stripe." |
Creazione del cliente Stripe fallita |
STRIPE_ALREADY_SUBSCRIBED |
"Già sottoscritto." |
Esiste una sottoscrizione attiva |
STRIPE_MISSING_PAYMENT_METHOD |
"Metodo di pagamento mancante." |
Nessun metodo di pagamento registrato |
STRIPE_CREATING_SUBSCRIPTION |
"Errore durante la creazione della sottoscrizione in Stripe." |
Creazione della sottoscrizione fallita |
STRIPE_UPDATING_SUBSCRIPTION |
"Errore durante l'aggiornamento della sottoscrizione in Stripe." |
Aggiornamento della sottoscrizione fallito |
STRIPE_CHECKOUT_SESSION |
"Errore durante la creazione della sessione di checkout in Stripe." |
Creazione della sessione di checkout fallita |
STRIPE_CUSTOMER_PORTAL |
"Errore durante la creazione del portale clienti in Stripe." |
Creazione della sessione del portale fallita |
STRIPE_TAX_ID |
"Impossibile salvare l'ID fiscale" |
Validazione/salvataggio dell'ID fiscale fallito |
PAYMENT_REQUIRED |
"Pagamento richiesto." |
La funzionalità richiede una sottoscrizione attiva |
NO_PAYMENT_REQUIRED |
"Nessun pagamento richiesto." |
Il pagamento non è necessario per l'operazione |
Errori di Autenticazione e Sessione
| Codice di Errore |
Messaggio |
Descrizione |
INVALID_CREDENTIALS |
"Credenziali non valide." |
Nome utente/password errati |
EXPIRED_RESET_TOKEN |
"Il token di reset è scaduto." |
Il token di reset della password è scaduto |
OAUTH_FAILED |
"Il processo OAuth è fallito." |
L'autenticazione OAuth è fallita |
SAML_NOT_ENABLED |
"SSO (SAML) non è abilitato." |
SSO SAML non configurato |
SSO_AUTO_PROVISION_DISABLED |
"L'auto provisioning è disabilitato." |
Impossibile creare automaticamente utenti SSO |
Limitazione della Frequenza
La limitazione della frequenza è gestita dal pacchetto graphql-rate-limit con diverse configurazioni:
| Tipo di Limite |
Finestra |
Max Richieste |
Applicato a |
| Standard |
60s |
500 |
Most queries/mutations |
| Sensitive |
300s |
10 |
Password reset, auth operations |
| Expensive |
60s |
20 |
Complex queries, bulk operations |
| Search |
60s |
60 |
Search operations |
| File Upload |
60s |
100 |
File upload operations |
Quando si è limitati, riceverai un errore standard di GraphQL con un messaggio che indica che il limite è stato superato.
Errori di Sistema e Interni
| Codice di Errore |
Messaggio |
Descrizione |
INTERNAL_SERVER_ERROR |
"Errore interno del server." |
Errore generico per errori non sicuri in produzione |
UNKNOWN_ERROR |
"Errore sconosciuto." |
Si è verificato un errore imprevisto |
RESOLVER_NOT_FOUND |
"Risolutore non trovato" |
Risolutore GraphQL mancante |
FIELD_NOT_IN_SCHEMA |
"Campo non presente nello schema" |
Il campo richiesto non esiste |
Migliori Pratiche per la Gestione degli Errori
Gestione Lato Client
try {
const result = await client.mutate({
mutation: CREATE_TODO,
variables: { input }
});
} catch (error) {
if (error.graphQLErrors?.length > 0) {
const errorCode = error.graphQLErrors[0].extensions?.code;
switch (errorCode) {
case 'UNAUTHENTICATED':
// Redirect to login
break;
case 'TODO_NOT_FOUND':
// Show "Record not found" message
break;
case 'VALIDATION_ERROR':
// Display validation errors
break;
default:
// Show generic error message
}
}
}
Scenari Comuni di Errore
- Autenticazione Richiesta:
UNAUTHENTICATED - L'utente deve effettuare il login
- Permesso Negato:
FORBIDDEN - L'utente non ha il ruolo/permissi richiesti
- Risorsa Non Trovata:
*_NOT_FOUND - La risorsa non esiste o l'utente non può accedervi
- Validazione Fallita:
VALIDATION_ERROR, BAD_USER_INPUT - Controlla i parametri di input
- Limite di Frequenza Superato: Controlla le intestazioni di limitazione della frequenza e implementa un backoff
- Pagamento Richiesto:
PAYMENT_REQUIRED - La funzionalità richiede una sottoscrizione
Documentazione Correlata