Zerobus Ingest : gestion des erreurs

Cette page décrit les codes d'erreur renvoyés par l'API Zerobus Ingest et la manière dont les clients doivent les gérer. Utilisez cette référence lors du diagnostic des requêtes échouées ou de l'implémentation d'une logique de gestion des erreurs dans votre intégration.

Format de réponse d'erreur

Les réponses d'erreur incluent un code d'erreur lisible par une machine et un message lisible par un être humain, fourni dans le format approprié pour votre protocole.

REST (JSON)

Les réponses d'erreur sont renvoyées au format JSON avec un code d'état HTTP approprié :

JSON

{
  "error_code": "NOT_FOUND",
  "message": "Table \"catalog.schema.table\" cannot be found."
}

Champ	Type	Description
code d'erreur	chaîne	Un code d'erreur lisible par machine identifiant la catégorie de défaillance. Utilisez ceci pour déterminer comment gérer l'erreur par programmation.
Message	chaîne	Une description lisible par un humain de l'erreur. Peut inclure des informations de diagnostic supplémentaires pour le dépannage. Ne parsez pas ce champ par programmation — son format peut changer sans préavis.

Champ	Type	Description
code d'erreur	chaîne	Un code d'erreur lisible par machine identifiant la catégorie de défaillance. Utilisez ceci pour déterminer comment gérer l'erreur par programmation.
Message	chaîne	Une description lisible par un humain de l'erreur. Peut inclure des informations de diagnostic supplémentaires pour le dépannage. Ne parsez pas ce champ par programmation — son format peut changer sans préavis.

gRPC

Les réponses d’erreur utilisent des codes d’état gRPC standard, fournis via les en-têtes de réponse :

Semi-remorque	Description
grpc-status	Un code de statut numérique (par exemple, 3 pour INVALID_ARGUMENT). Utilisez ceci pour déterminer comment gérer l'erreur par programmation.
grpc-message	Une description lisible par un humain de l'erreur. Peut inclure des informations de diagnostic supplémentaires pour le dépannage. Ne parsez pas ce champ par programmation — son format peut changer sans préavis.

Semi-remorque	Description
grpc-status	Un code de statut numérique (par exemple, 3 pour INVALID_ARGUMENT). Utilisez ceci pour déterminer comment gérer l'erreur par programmation.
grpc-message	Une description lisible par un humain de l'erreur. Peut inclure des informations de diagnostic supplémentaires pour le dépannage. Ne parsez pas ce champ par programmation — son format peut changer sans préavis.

Codes d'erreur

Les sections suivantes décrivent les codes d'erreur renvoyés par l'API Zerobus Ingest, leurs codes de niveau protocole correspondants et le comportement client recommandé.

Erreurs client

Ces erreurs indiquent un problème avec la requête. Ne réessayez pas sans modifier la requête.

Code d'erreur (REST)	Code gRPC	Statut HTTP	Description	Action recommandée
INVALID_PARAMETER_VALUE	INVALID_ARGUMENT(3)	400	La requête contient une entrée non valide ou mal formée, telle qu'un champ obligatoire manquant, un schéma non valide ou un format d'enregistrement non pris en charge.	Veuillez corriger la requête et la soumettre à nouveau. Examinez le champ message pour des détails sur le paramètre non valide.
NOT_FOUND	NOT_FOUND(5)	404	La ressource demandée n'existe pas. Par exemple, la table spécifiée est introuvable.	Vérifiez que le nom de la ressource est correct et qu'elle existe.
NOT_IMPLEMENTED	UNIMPLEMENTED(12)	501	L'Opération demandée n'est pas prise en charge. Par exemple, la table utilise une fonctionnalité ou un format de données non pris en charge.	Ne pas réessayer. Vérifiez le champ message pour plus de détails sur ce qui n'est pas pris en charge.

Code d'erreur (REST)	Code gRPC	Statut HTTP	Description	Action recommandée
INVALID_PARAMETER_VALUE	INVALID_ARGUMENT(3)	400	La requête contient une entrée non valide ou mal formée, telle qu'un champ obligatoire manquant, un schéma non valide ou un format d'enregistrement non pris en charge.	Veuillez corriger la requête et la soumettre à nouveau. Examinez le champ message pour des détails sur le paramètre non valide.
NOT_FOUND	NOT_FOUND(5)	404	La ressource demandée n'existe pas. Par exemple, la table spécifiée est introuvable.	Vérifiez que le nom de la ressource est correct et qu'elle existe.
NOT_IMPLEMENTED	UNIMPLEMENTED(12)	501	L'Opération demandée n'est pas prise en charge. Par exemple, la table utilise une fonctionnalité ou un format de données non pris en charge.	Ne pas réessayer. Vérifiez le champ message pour plus de détails sur ce qui n'est pas pris en charge.

Erreurs d'authentification et d'autorisation

Ces erreurs indiquent des problèmes avec l'identité ou les permissions de l'appelant. Ne réessayez pas avec les mêmes identifiants.

Code d'erreur (REST)	Code gRPC	Statut HTTP	Description	Action recommandée
UNAUTHENTICATED	UNAUTHENTICATED(16)	401	La requête ne dispose pas d'identifiants d'authentification valides. Le jeton peut être manquant, vide, expiré ou invalide.	Veuillez refresh ou fournir un jeton d'authentification valide, puis réessayer.
PERMISSION_DENIED	PERMISSION_DENIED(7)	403	L'appelant n'a pas les privilèges suffisants pour effectuer l'opération demandée sur la ressource spécifiée.	Vérifiez que l'appelant dispose des privilèges requis (par exemple, MODIFY, SELECT, USE_CATALOG, USE_SCHEMA) sur la ressource cible.

Code d'erreur (REST)	Code gRPC	Statut HTTP	Description	Action recommandée
UNAUTHENTICATED	UNAUTHENTICATED(16)	401	La requête ne dispose pas d'identifiants d'authentification valides. Le jeton peut être manquant, vide, expiré ou invalide.	Veuillez refresh ou fournir un jeton d'authentification valide, puis réessayer.
PERMISSION_DENIED	PERMISSION_DENIED(7)	403	L'appelant n'a pas les privilèges suffisants pour effectuer l'opération demandée sur la ressource spécifiée.	Vérifiez que l'appelant dispose des privilèges requis (par exemple, MODIFY, SELECT, USE_CATALOG, USE_SCHEMA) sur la ressource cible.

Erreurs de serveur

Ces erreurs indiquent un problème côté serveur. Nouvelle tentative avec intervalle exponentiel et jitter.

Code d'erreur (REST)	Code gRPC	Statut HTTP	Description	Action recommandée
UNAVAILABLE	UNAVAILABLE(14)	503	Le service est temporairement incapable de traiter la requête. Il s'agit généralement d'une condition transitoire.	Nouvelle tentative avec un intervalle exponentiel et une gigue.
RESOURCE_EXHAUSTED	RESOURCE_EXHAUSTED(8)	429	Le service rejette les demandes en raison des limites de ressources.	Réduisez la simultanéité des requêtes si possible. Nouvelle tentative avec intervalle exponentiel et jitter.
INTERNAL_ERROR	INTERNAL(13)	500	Une erreur interne inattendue s'est produite.	Ne pas réessayer. Veuillez contacter le support et fournir la réponse d'erreur complète à des fins de diagnostic.

Code d'erreur (REST)	Code gRPC	Statut HTTP	Description	Action recommandée
UNAVAILABLE	UNAVAILABLE(14)	503	Le service est temporairement incapable de traiter la requête. Il s'agit généralement d'une condition transitoire.	Nouvelle tentative avec un intervalle exponentiel et une gigue.
RESOURCE_EXHAUSTED	RESOURCE_EXHAUSTED(8)	429	Le service rejette les demandes en raison des limites de ressources.	Réduisez la simultanéité des requêtes si possible. Nouvelle tentative avec intervalle exponentiel et jitter.
INTERNAL_ERROR	INTERNAL(13)	500	Une erreur interne inattendue s'est produite.	Ne pas réessayer. Veuillez contacter le support et fournir la réponse d'erreur complète à des fins de diagnostic.