Gestão de erros por Ingest de Zerobus

Esta página descreve os códigos de erro retornados pela API Zerobus Ingest e como os clientes devem tratá-los. Use esta referência ao diagnosticar pedidos falhados ou implementar lógica de gestão de erros na sua integração.

Formato de resposta a erro

As respostas ao erro incluem um código de erro legível por máquina e uma mensagem legível por humanos, entregues no formato apropriado ao seu protocolo.

REST (JSON)

As respostas de erro são devolvidas como JSON com um código de estado HTTP apropriado:

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

Campo	Type	Descrição
código de erro	cadeia (de caracteres)	Um código de erro legível por máquina que identifica a categoria de falha. Use isto para determinar como lidar programaticamente com o erro.
mensagem	cadeia (de caracteres)	Uma descrição do erro legível por humanos. Pode incluir informações de diagnóstico adicionais para resolução de problemas. Não analise este campo programaticamente, pois o seu formato pode mudar sem aviso.

gRPC

As respostas de erro utilizam os códigos de estado padrão do gRPC, transmitidos através de trilhas de resposta.

Trailer	Descrição
Estatuto GRPC	Um código de estado numérico (por exemplo, 3 para INVALID_ARGUMENT). Use isto para determinar como lidar programaticamente com o erro.
grpc-message	Uma descrição do erro legível por humanos. Pode incluir informações de diagnóstico adicionais para resolução de problemas. Não analise este campo programaticamente, pois o seu formato pode mudar sem aviso.

Códigos de erro

As secções seguintes descrevem os códigos de erro devolvidos pela API Zerobus Ingest, os respetivos códigos ao nível do protocolo e o comportamento recomendado do cliente.

Erros do cliente

Estes erros indicam um problema com o pedido. Não tente novamente sem modificar o pedido.

Código de erro (REST)	Código gRPC	Estado HTTP	Descrição	Ação recomendada
INVALID_PARAMETER_VALUE	INVALID_ARGUMENT(3)	400	O pedido contém entrada inválida ou mal formada, como um campo obrigatório em falta, um esquema inválido ou um formato de registo não suportado.	Corrige o pedido e volta a submeter. Inspecione o message campo para detalhes sobre qual o parâmetro inválido.
NOT_FOUND	NOT_FOUND(5)	404	O recurso solicitado não existe. Por exemplo, a tabela especificada não pode ser encontrada.	Verifica se o nome do recurso está correto e que existe.
NOT_IMPLEMENTED	UNIMPLEMENTED(12)	501	A operação solicitada não é suportada. Por exemplo, a tabela utiliza uma característica ou formato de dados não suportado.	Não volte a tentar. Consulte o message campo para detalhes sobre o que não é suportado.

Erros de autenticação e autorização

Estes erros indicam problemas com a identidade ou permissões do chamador. Não tente novamente com as mesmas credenciais.

Código de erro (REST)	Código gRPC	Estado HTTP	Descrição	Ação recomendada
UNAUTHENTICATED	UNAUTHENTICATED(16)	401	O pedido não tem credenciais de autenticação válidas. O token pode estar em falta, vazio, expirado ou inválido.	Atualize ou forneça um token de autenticação válido e tente novamente.
PERMISSION_DENIED	PERMISSION_DENIED(7)	403	O chamador não tem privilégios suficientes para realizar a operação solicitada no recurso especificado.	Verifique se o chamador tem os privilégios necessários (por exemplo, MODIFY, SELECT, USE_CATALOG, USE_SCHEMA) sobre o recurso alvo.

Erros de servidor

Estes erros indicam um problema do lado do servidor. Tenta novamente com recuo exponencial e tremores.

Código de erro (REST)	Código gRPC	Estado HTTP	Descrição	Ação recomendada
UNAVAILABLE	UNAVAILABLE(14)	503	O serviço está temporariamente incapaz de tratar do pedido. Isto é tipicamente uma condição transitória.	Tenta novamente com recuo exponencial e tremores.
RESOURCE_EXHAUSTED	RESOURCE_EXHAUSTED(8)	429	O serviço está a rejeitar pedidos devido a limitações de recursos.	Reduza a simultaneidade dos pedidos, se possível. Tenta novamente com recuo exponencial e tremores.
INTERNAL_ERROR	INTERNAL(13)	500	Ocorreu um erro interno inesperado.	Não volte a tentar. Contacte o apoio técnico e forneça a resposta completa ao erro para diagnóstico.