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:
{
"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 legível por humanos do erro. Pode incluir informações de diagnóstico adicionais para solução de problemas. Não analise este campo programaticamente, pois 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.: |
mensagem-grpc | Uma descrição legível por humanos do erro. Pode incluir informações de diagnóstico adicionais para solução de problemas. Não analise este campo programaticamente, pois 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 |
|---|---|---|---|---|
|
| 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 |
|
| 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. |
|
| 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 |
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 |
|---|---|---|---|---|
|
| 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. |
|
| 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, |
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 |
|---|---|---|---|---|
|
| 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. |
|
| 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. |
|
| 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. |