Tratamento de erros de ingestão do Zerobus

Esta página descreve os códigos de erro retornados pela API Zerobus Ingest e como os clientes devem lidar com eles. Utilize esta referência ao diagnosticar solicitações com falha ou ao implementar a lógica de tratamento de erros em sua integração.

Formato de resposta de erro

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

REST (JSON)

As respostas de erro são retornadas em formato JSON com o código de status HTTP apropriado:

JSON

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

campo	Tipo	Descrição
código_de_erro	string	Um código de erro legível por máquina que identifica a categoria da falha. Use isso para determinar como lidar com o erro programaticamente.
Mensagem	string	Uma descrição do erro em linguagem acessível a humanos. Pode incluir informações de diagnóstico adicionais para solução de problemas. Não analise este campo programaticamente — seu formato pode mudar sem aviso prévio.

gRPC

As respostas de erro utilizam códigos de status gRPC padrão, entregues por meio de trailers de resposta:

Reboque	Descrição
status-grpc	Um código de status numérico (ex.: 3 para INVALID_ARGUMENT). Use isso para determinar como lidar com o erro programaticamente.
mensagem-grpc	Uma descrição do erro em linguagem acessível a humanos. Pode incluir informações de diagnóstico adicionais para solução de problemas. Não analise este campo programaticamente — seu formato pode mudar sem aviso prévio.

Códigos de erro

As seções a seguir descrevem os códigos de erro retornados pela API Zerobus Ingest, seus códigos correspondentes em nível de protocolo e o comportamento recomendado para o cliente.

Erros do cliente

Esses erros indicam um problema com a solicitação. Não tente novamente sem modificar a solicitação.

Código de erro (REST)	código gRPC	Status HTTP	Descrição	Ação recomendada
INVALID_PARAMETER_VALUE	INVALID_ARGUMENT(3)	400	A solicitação contém dados de entrada inválidos ou malformados, como um campo obrigatório ausente, um esquema inválido ou um formato de registro não suportado.	Corrija a solicitação e envie-a novamente. Inspecione o campo message para obter detalhes sobre qual parâmetro é inválido.
NOT_FOUND	NOT_FOUND(5)	404	O recurso solicitado não existe. Por exemplo, a tabela especificada não foi encontrada.	Verifique se o nome do recurso está correto e se ele existe.
NOT_IMPLEMENTED	UNIMPLEMENTED(12)	501	A operação solicitada não é suportada. Por exemplo, a tabela utiliza um recurso ou formato de dados não suportado.	Não tente novamente. Verifique o campo message para obter detalhes sobre o que não é suportado.

Erros de autenticação e autorização

Esses erros indicam problemas com a identidade ou as permissões de quem está ligando. Não tente novamente com as mesmas credenciais.

Código de erro (REST)	código gRPC	Status HTTP	Descrição	Ação recomendada
UNAUTHENTICATED	UNAUTHENTICATED(16)	401	A solicitação não possui credenciais de autenticação válidas. Os tokens podem estar ausentes, vazios, expirados ou inválidos.	Atualize a página ou forneça um token de autenticação válido e tente novamente.
PERMISSION_DENIED	PERMISSION_DENIED(7)	403	O solicitante não possui privilégios suficientes para executar as operações solicitadas no recurso especificado.	Verifique se o chamador tem os privilégios necessários (por exemplo, MODIFY, SELECT, USE_CATALOG, USE_SCHEMA) no recurso de destino.

Erros do servidor

Esses erros indicam um problema no servidor. Tente novamente com recuo exponencial e jitter.

Código de erro (REST)	código gRPC	Status HTTP	Descrição	Ação recomendada
UNAVAILABLE	UNAVAILABLE(14)	503	O serviço está temporariamente indisponível para processar a solicitação. Essa condição é normalmente transitória.	Tente novamente com recuo exponencial e jitter.
RESOURCE_EXHAUSTED	RESOURCE_EXHAUSTED(8)	429	O serviço está rejeitando solicitações devido aos limites de recurso.	Reduza a simultaneidade de requisições, se possível. Tente novamente com recuo exponencial e jitter.
INTERNAL_ERROR	INTERNAL(13)	500	Ocorreu um erro interno inesperado.	Não tente novamente. Entre em contato com o suporte e forneça a resposta completa do erro para que possamos diagnosticar o problema.