Tratamento de erros de ingestão do Zerobus

Esta página descreve os códigos de erro retornados pela API de Ingestão do Zerobus e como os clientes devem lidar com eles. Use essa referência ao diagnosticar solicitações com falha ou 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 pelo computador e uma mensagem legível por humanos, entregue no formato apropriado para o protocolo.

DESCANSO (JSON)

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

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

Campo	Tipo	Descrição
código_de_erro	cadeia	Um código de erro legível pelo computador que identifica a categoria de falha. Use isso para determinar como lidar com o erro programaticamente.
mensagem	cadeia	Uma descrição do erro legível para humanos. Pode incluir informações adicionais de diagnóstico para solução de problemas. Não analise esse campo programaticamente, pois seu formato pode mudar sem aviso.

gRPC

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

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

Códigos de erro

As seções a seguir descrevem os códigos de erro retornados pela API de Ingestão do Zerobus, seus códigos de nível de protocolo correspondentes e o comportamento recomendado do 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 entrada inválida ou malformada, como um campo necessário ausente, um esquema inválido ou um formato de registro sem suporte.	Corrija a solicitação e reenvie a solicitação. Inspecione o message campo 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 pode ser encontrada.	Verifique se o nome do recurso está correto e se ele existe.
NOT_IMPLEMENTED	UNIMPLEMENTED(12)	501	Não há suporte para a operação solicitada. Por exemplo, a tabela usa um formato de dados ou recurso sem suporte.	Não tente novamente. Verifique o message campo para obter detalhes sobre o que não tem suporte.

Erros de autorização e autenticação

Esses 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	Status HTTP	Descrição	Ação recomendada
UNAUTHENTICATED	UNAUTHENTICATED(16)	401	A solicitação não tem credenciais de autenticação válidas. O token pode estar ausente, 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 executar 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) no recurso de destino.

Erros do servidor

Esses erros indicam um problema no lado do servidor. Tente novamente com retirada exponencial e tremulação.

Código de erro (REST)	código gRPC	Status HTTP	Descrição	Ação recomendada
UNAVAILABLE	UNAVAILABLE(14)	503	O serviço não consegue lidar temporariamente com a solicitação. Normalmente, essa é uma condição transitória.	Tente novamente com retirada exponencial e tremulação.
RESOURCE_EXHAUSTED	RESOURCE_EXHAUSTED(8)	429	O serviço está rejeitando solicitações devido aos limites de recursos.	Reduza a concorrência de solicitações, se possível. Tente novamente com retirada exponencial e tremulação.
INTERNAL_ERROR	INTERNAL(13)	500	Ocorreu um erro interno inesperado.	Não tente novamente. Contate o suporte e forneça a resposta de erro completa para o diagnóstico.