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.
  • Last updated on