Gestion des erreurs d’ingestion Zerobus

Gestion des erreurs

Cette section décrit comment les erreurs sont retournées par l’API d’ingestion Zerobus et comment les clients doivent les gérer.

Format de réponse d’erreur

REST (JSON)

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

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

Champ	Type	Description
code_erreur	ficelle	Code d’erreur lisible par l’ordinateur identifiant la catégorie d’échec. Utilisez-la pour déterminer comment gérer l’erreur par programme.
message	ficelle	Une description de l’erreur à l’intention des utilisateurs. Peut inclure des informations de diagnostic supplémentaires pour la résolution des problèmes. N’analysez pas ce champ par programmation : son format peut changer sans préavis.

gPRC

Les réponses d’erreur utilisent des codes d’état gRPC standard, remis via des bandes-annonces de réponse :

Bande-annonce	Description
grpc-status	Code d’état numérique (par exemple, 3 pour INVALID_ARGUMENT). Utilisez-la pour déterminer comment gérer l’erreur par programme.
grpc-message	Une description de l’erreur à l’intention des utilisateurs. Peut inclure des informations de diagnostic supplémentaires pour la résolution des problèmes. N’analysez pas ce champ par programmation : son format peut changer sans préavis.

Codes d’erreur

Le tableau suivant répertorie tous les codes d’erreur retournés par l’API Zerobus Ingest, leurs codes de niveau protocole correspondants et le comportement client recommandé.

Erreurs du 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	État HTTP	Description	Action recommandée
INVALID_PARAMETER_VALUE	INVALID_ARGUMENT(3)	400	La requête contient une entrée non valide ou incorrecte, telle qu’un champ obligatoire manquant, un schéma non valide ou un format d’enregistrement non pris en charge.	Corrigez la demande et soumettez à nouveau. Examinez le message champ pour plus d’informations sur le paramètre qui n’est pas 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’il existe.
NOT_IMPLEMENTED	UNIMPLEMENTED(12)	5:01	L’opération demandée n’est pas prise en charge. Par exemple, le tableau utilise une fonctionnalité ou un format de données non pris en charge.	Ne réessayez pas. Vérifiez le message champ pour plus d’informations sur ce qui n’est pas pris en charge.

Erreurs d’authentification et d’autorisation

Ces erreurs indiquent des problèmes liés à l’identité ou aux autorisations de l’appelant. Ne réessayez pas avec les mêmes informations d’identification.

Code d’erreur (REST)	Code gRPC	État HTTP	Description	Action recommandée
UNAUTHENTICATED	UNAUTHENTICATED(16)	401	La demande n’a pas de données d'identification valides. Le jeton peut être manquant, vide, expiré ou non valide.	Actualisez ou fournissez un jeton d’authentification valide et réessayez.
PERMISSION_DENIED	PERMISSION_DENIED(7)	403	L’appelant n’a pas suffisamment de privilèges 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, , SELECTUSE_CATALOG, USE_SCHEMA) sur la ressource cible.

Erreurs de serveur

Ces erreurs indiquent un problème côté serveur. Réessayez avec un décalage exponentiel et une instabilité.

Code d’erreur (REST)	Code gRPC	État HTTP	Description
UNAVAILABLE	UNAVAILABLE(14)	503	Le service ne peut pas gérer temporairement la requête. Il s’agit généralement d’une condition temporaire. Réessayez avec un backoff exponentiel et une gigue.
RESOURCE_EXHAUSTED	RESOURCE_EXHAUSTED(8)	429	Le service rejette les demandes en raison de limites de ressources. Réduisez la concurrence des demandes si possible. Réessayez avec un retrait exponentiel et une gigue.
INTERNAL_ERROR	INTERNAL_ERROR(13)	500	Une erreur interne inattendue s’est produite. Ne réessayez pas. Contactez le support et fournissez le message d’erreur complet pour le diagnostic.