Gestão de Erros de Ingestão Zerobus

Tratamento de erros

Esta secção descreve como os erros são devolvidos pela API Zerobus Ingest e como os clientes devem lidá-los.

Formato de Resposta ao Erro

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 — o seu formato pode mudar sem aviso.

gPRC

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 — o seu formato pode mudar sem aviso.

Códigos de erro

A tabela seguinte lista todos 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
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_ERROR(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.