Référence complète de tous les codes d'erreur dans l'API GraphQL de Blue, organisée par catégorie
L'API GraphQL de Blue renvoie des erreurs dans un format standardisé suivant la spécification GraphQL. Lorsqu'une erreur se produit, la réponse inclut un tableau errors avec des informations détaillées sur ce qui a mal tourné.
Exemple de réponse d'erreur
{
"errors": [
{
"message": "Todo was not found.",
"extensions": {
"code": "TODO_NOT_FOUND"
}
}
]
}
Structure de l'erreur
Chaque objet d'erreur contient :
- message : Une description lisible par l'homme de l'erreur
- extensions.code : Un code d'erreur lisible par machine pour un traitement programmatique
Sécurité des erreurs en production
Blue met en œuvre un système de sécurité pour l'exposition des erreurs :
- Erreurs sûres : Afficher les codes d'erreur et messages réels aux clients
- Erreurs non sûres : Retourner un
INTERNAL_SERVER_ERROR générique pour cacher les détails sensibles
- Ressource non trouvée : Toutes les erreurs
*_NOT_FOUND sont considérées comme sûres et toujours exposées
Catégories d'erreur
Blue définit 108 codes d'erreur personnalisés organisés en les catégories suivantes :
Erreurs d'authentification et d'autorisation
| Code d'erreur |
Message |
Description |
UNAUTHENTICATED |
"Authentification requise." |
La demande nécessite une authentification mais aucune n'a été fournie |
FORBIDDEN |
"Vous n'êtes pas autorisé." |
Authentifié mais manque des autorisations requises |
Erreurs de ressource non trouvée (52 au total)
Ressources principales
| Code d'erreur |
Message |
Description |
TODO_NOT_FOUND |
"Todo non trouvé." |
L'enregistrement/todo n'existe pas ou l'utilisateur n'a pas accès |
TODO_LIST_NOT_FOUND |
"Liste de todo non trouvée." |
La liste n'existe pas ou l'utilisateur n'a pas accès |
PROJECT_NOT_FOUND |
"Projet non trouvé." |
Le projet n'existe pas ou l'utilisateur n'a pas accès |
COMPANY_NOT_FOUND |
"Société non trouvée." |
La société n'existe pas ou l'utilisateur n'a pas accès |
USER_NOT_FOUND |
"Utilisateur non trouvé." |
L'utilisateur n'existe pas dans le système |
| Code d'erreur |
Message |
Description |
CUSTOM_FIELD_NOT_FOUND |
"Champ personnalisé non trouvé." |
Le champ personnalisé n'existe pas |
CUSTOM_FIELD_OPTION_NOT_FOUND |
"Option de champ personnalisé non trouvée." |
L'option de champ sélectionné n'existe pas |
FORM_NOT_FOUND |
"Formulaire non trouvé." |
Le modèle de formulaire n'existe pas |
FORM_FIELD_NOT_FOUND |
"Champ de formulaire non trouvé." |
Le champ de formulaire n'existe pas |
Composants de projet
| Code d'erreur |
Message |
Description |
TAG_NOT_FOUND |
"Tag non trouvé." |
Le tag n'existe pas dans le projet |
AUTOMATION_NOT_FOUND |
"Automatisation non trouvée." |
La règle d'automatisation n'existe pas |
CHART_NOT_FOUND |
"Graphique non trouvé." |
Le graphique du tableau de bord n'existe pas |
WEBHOOK_NOT_FOUND |
"Webhook non trouvé." |
La configuration du webhook n'existe pas |
TEMPLATE_NOT_FOUND |
"Modèle non trouvé." |
Le modèle de projet n'existe pas |
| Code d'erreur |
Message |
Description |
COMMENT_NOT_FOUND |
"Commentaire non trouvé." |
Le commentaire n'existe pas |
ACTIVITY_NOT_FOUND |
"Activité non trouvée." |
L'entrée du journal d'activité n'existe pas |
REACTION_NOT_FOUND |
"Réaction non trouvée." |
La réaction au commentaire n'existe pas |
Autres ressources
| Code d'erreur |
Message |
Description |
FILE_NOT_FOUND |
"Fichier non trouvé." |
L'attachement de fichier n'existe pas |
SUBSCRIPTION_NOT_FOUND |
"Abonnement non trouvé." |
L'abonnement de facturation n'existe pas |
INVOICE_NOT_FOUND |
"Facture non trouvée." |
L'enregistrement de la facture n'existe pas |
CHECKLIST_NOT_FOUND |
"Liste de contrôle non trouvée." |
La liste de contrôle n'existe pas |
CHECKLIST_ITEM_NOT_FOUND |
"Élément de liste de contrôle non trouvé." |
L'élément de liste de contrôle n'existe pas |
PROJECT_ROLE_NOT_FOUND |
"Rôle de projet non trouvé." |
Le rôle de projet personnalisé n'existe pas |
PROJECT_ACCESS_NOT_FOUND |
"Accès au projet non trouvé." |
L'accès de l'utilisateur au projet n'existe pas |
NOTIFICATION_NOT_FOUND |
"Notification non trouvée." |
La notification n'existe pas |
DASHBOARD_NOT_FOUND |
"Tableau de bord non trouvé." |
Le tableau de bord n'existe pas |
KEY_NOT_FOUND |
"Clé non trouvée." |
La clé des paramètres n'existe pas |
Erreurs de validation
| Code d'erreur |
Message |
Description |
BAD_USER_INPUT |
"Entrée invalide." |
Échec de validation d'entrée générique |
VALIDATION_ERROR |
"Paramètres invalides" |
Les paramètres de la demande ont échoué à la validation |
BAD_EMAIL |
"Vous devez entrer un email valide." |
Format d'email invalide |
INVALID_IDS |
"Identifiants invalides." |
Un ou plusieurs ID dans la demande sont invalides |
PHONE_INVALID |
"Téléphone invalide." |
Format de numéro de téléphone invalide |
URL_INVALID |
"URL invalide." |
Format d'URL invalide |
INVALID_RECURRING_DUE_DATE |
"Date d'échéance invalide pour la tâche récurrente" |
Échec de validation de la date de tâche récurrente |
INVALID_COLOR |
"Couleur invalide" |
La valeur de couleur ne correspond pas au format attendu |
Erreurs de logique métier
Limites et quotas
| Code d'erreur |
Message |
Description |
COMPANY_LIMIT |
"Vous avez atteint la limite de sociétés pour votre compte." |
Limite maximale de sociétés atteinte |
PROJECT_LIMIT |
"Vous avez atteint la limite de projets pour votre société." |
Limite maximale de projets atteinte |
USER_LIMIT |
"Vous avez atteint la limite d'utilisateurs pour votre société." |
Limite maximale d'utilisateurs atteinte |
PROJECT_TEMPLATE_LIMIT |
"Vous avez atteint la limite de modèles pour votre société." |
Limite maximale de modèles atteinte |
CUSTOM_FIELD_LIMIT |
"Limite de champs personnalisés atteinte." |
Limite maximale de champs personnalisés atteinte |
TODO_LIST_LIMIT |
"Vous avez atteint la limite de listes pour votre projet." |
Limite maximale de listes par projet |
TOO_MANY_TODOS |
"Trop de todos." |
Limite d'enregistrements dépassée |
TOO_MANY_OPTIONS |
"Trop d'options." |
Limite d'options de champ sélectionné dépassée |
MAX_FILE_SIZE |
"La taille maximale du fichier est de 4,8 Go" |
Limite de taille de téléchargement de fichier dépassée |
Conflits de ressources
| Code d'erreur |
Message |
Description |
TAG_ALREADY_EXISTS |
"Le tag existe déjà." |
Un tag avec le même nom existe dans le projet |
COMPANY_SLUG_ALREADY_EXISTS |
"La société existe déjà." |
Le slug/URL de la société est pris |
USER_ALREADY_EXISTS |
"L'utilisateur existe déjà." |
L'email de l'utilisateur est déjà enregistré |
ALREADY_INVITED |
"L'utilisateur a déjà été invité." |
L'utilisateur a déjà une invitation en attente |
USER_ALREADY_IN_PROJECT |
"L'utilisateur est déjà sur ce projet." |
L'utilisateur a déjà accès au projet |
FILE_TYPE_NOT_ALLOWED |
"Type de fichier non autorisé." |
Le type de fichier téléchargé est restreint |
Erreurs de permission et d'accès
| Code d'erreur |
Message |
Description |
UNABLE_TO_DELETE_ONLY_ADMIN |
"Impossible de supprimer le seul administrateur de la société." |
Impossible de retirer le dernier administrateur |
UNABLE_TO_UPDATE_OWNER |
"Impossible de mettre à jour le PROPRIÉTAIRE." |
Impossible de modifier les autorisations du propriétaire |
TODO_LIST_IS_HIDDEN |
"La liste de todo est cachée." |
Liste cachée du rôle de l'utilisateur |
COMPANY_NOT_ACTIVE |
"La société n'est pas active." |
Abonnement de la société inactif |
PROJECT_NOT_ACTIVE |
"Le projet n'est pas actif." |
Le projet est archivé/inactif |
Erreurs d'intégrité des données
| Code d'erreur |
Message |
Description |
UNABLE_TO_DELETE_LIST_WITH_TODOS |
"Impossible de supprimer la liste avec des todos." |
La liste doit être vide pour être supprimée |
UNABLE_TO_DELTE_FILE |
"Impossible de supprimer le fichier." |
Échec de la suppression du fichier (erreur de code) |
UNABLE_TO_MOVE_TODO |
"Impossible de déplacer le todo." |
Impossible de déplacer l'enregistrement entre les listes |
DEPENDENCY_HAS_DEPENDENCY |
"La dépendance a une dépendance" |
Dépendance circulaire détectée |
TODO_DEPENDS_ON_ITSELF |
"Le todo dépend de lui-même" |
Dépendance auto-référentielle |
Erreurs Stripe/Paiement
| Code d'erreur |
Message |
Description |
STRIPE_CREATING_CUSTOMER |
"Erreur lors de la création du client dans Stripe." |
Échec de la création du client Stripe |
STRIPE_ALREADY_SUBSCRIBED |
"Déjà abonné." |
Un abonnement actif existe |
STRIPE_MISSING_PAYMENT_METHOD |
"Méthode de paiement manquante." |
Aucune méthode de paiement enregistrée |
STRIPE_CREATING_SUBSCRIPTION |
"Erreur lors de la création de l'abonnement dans Stripe." |
Échec de la création de l'abonnement |
STRIPE_UPDATING_SUBSCRIPTION |
"Erreur lors de la mise à jour de l'abonnement dans Stripe." |
Échec de la mise à jour de l'abonnement |
STRIPE_CHECKOUT_SESSION |
"Erreur lors de la création de la session de paiement dans Stripe." |
Échec de la création de la session de paiement |
STRIPE_CUSTOMER_PORTAL |
"Erreur lors de la création du portail client dans Stripe." |
Échec de la création de la session du portail |
STRIPE_TAX_ID |
"Impossible d'enregistrer l'ID fiscal" |
Échec de validation/sauvegarde de l'ID fiscal |
PAYMENT_REQUIRED |
"Paiement requis." |
La fonctionnalité nécessite un abonnement actif |
NO_PAYMENT_REQUIRED |
"Aucun paiement requis." |
Aucun paiement nécessaire pour l'opération |
Erreurs d'authentification et de session
| Code d'erreur |
Message |
Description |
INVALID_CREDENTIALS |
"Identifiants invalides." |
Nom d'utilisateur/mot de passe incorrect |
EXPIRED_RESET_TOKEN |
"Le jeton de réinitialisation a expiré." |
Le jeton de réinitialisation de mot de passe a expiré |
OAUTH_FAILED |
"Le processus OAuth a échoué." |
Échec de l'authentification OAuth |
SAML_NOT_ENABLED |
"SSO (SAML) n'est pas activé." |
SSO SAML non configuré |
SSO_AUTO_PROVISION_DISABLED |
"La provision automatique est désactivée." |
Impossible de créer automatiquement des utilisateurs SSO |
Limitation de débit
La limitation de débit est gérée par le paquet graphql-rate-limit avec différentes configurations :
| Type de limite |
Fenêtre |
Max Requêtes |
Appliqué à |
| 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 |
Lorsqu'une limitation de débit est appliquée, vous recevrez une erreur GraphQL standard avec un message indiquant que la limite a été dépassée.
Erreurs système et internes
| Code d'erreur |
Message |
Description |
INTERNAL_SERVER_ERROR |
"Erreur interne du serveur." |
Erreur générique pour les erreurs non sûres en production |
UNKNOWN_ERROR |
"Erreur inconnue." |
Une erreur inattendue s'est produite |
RESOLVER_NOT_FOUND |
"Résolveur non trouvé" |
Résolveur GraphQL manquant |
FIELD_NOT_IN_SCHEMA |
"Champ non dans le schéma" |
Le champ demandé n'existe pas |
Meilleures pratiques de gestion des erreurs
Gestion côté 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
}
}
}
Scénarios d'erreur courants
- Authentification requise :
UNAUTHENTICATED - L'utilisateur doit se connecter
- Permission refusée :
FORBIDDEN - L'utilisateur manque du rôle/permission requis
- Ressource non trouvée :
*_NOT_FOUND - La ressource n'existe pas ou l'utilisateur ne peut pas y accéder
- Validation échouée :
VALIDATION_ERROR, BAD_USER_INPUT - Vérifiez les paramètres d'entrée
- Limitation de débit : Vérifiez les en-têtes de limitation de débit et implémentez un retour en arrière
- Paiement requis :
PAYMENT_REQUIRED - La fonctionnalité nécessite un abonnement
Documentation connexe