Referência
Respostas e tratamento de erros
Esta página organiza as falhas de forma conceitual para orientar o comportamento do sistema integrador, sem definir códigos ou corpos de resposta não confirmados.
Categorias de erro
| Categoria | O que significa | Ação recomendada | Deve repetir a requisição? |
|---|---|---|---|
| Falha de autenticação | O token não foi aceito ou não permite a operação esperada. | Conferir credencial, ambiente e forma de envio do cabeçalho. | Não, até corrigir a credencial |
| Metadados inválidos | Os dados enviados em metadata não atendem à configuração da integração. |
Validar estrutura, tipos e valores antes do novo envio. | Não, até corrigir os dados |
| Arquivo inválido | O campo audio não pôde ser aceito para processamento. |
Confirmar o arquivo enviado e a configuração efetiva do ambiente. | Não, até corrigir os dados |
| Registro duplicado | O envio pode estar relacionado a um identificador já registrado. | Consultar o registro existente e revisar a estratégia de idempotência. | Não, sem alterar o identificador ou confirmar o registro existente |
| Erro de processamento | A solicitação foi recebida, mas houve falha em etapa posterior do fluxo. | Consultar o estado do resultado e avaliar reprocessamento conforme a política do ambiente. | Consultar o resultado antes de reenviar |
| Falha de transcrição | A etapa de transcrição não produziu o resultado esperado. | Registrar a falha, correlacionar com a gravação e avaliar nova tentativa conforme orientação operacional. | Consultar o resultado antes de reenviar |
| Falha de avaliação | A etapa de avaliação por IA não produziu o resultado esperado. | Registrar a falha, preservar a transcrição quando disponível e avaliar reprocessamento. | Consultar o resultado antes de reenviar |
| Indisponibilidade temporária | O serviço ou alguma dependência pode estar temporariamente indisponível. | Aguardar e repetir com política controlada de retry. | Sim, com backoff, para falhas temporárias |
Erro síncrono versus erro assíncrono
Erro síncrono de recebimento
Ocorre durante a chamada inicial, antes de a solicitação seguir para processamento. Normalmente está relacionado a autenticação, metadados, arquivo ou duplicidade detectada no recebimento.
Erro assíncrono de processamento
Ocorre depois que a solicitação foi registrada e encaminhada para fila. Pode aparecer em etapas como transcrição, avaliação por IA ou persistência de resultado.
Estratégia recomendada de retry
- Usar exponential backoff.
- Definir limite de tentativas no cliente.
- Adicionar jitter para evitar rajadas simultâneas.
- Configurar timeout nas chamadas HTTP.
- Manter idempotência por identificador externo.
- Registrar correlation ID para rastreabilidade.
- Não repetir imediatamente em loop.
Orientação operacional
Antes de reenviar uma gravação, verifique se a primeira tentativa foi registrada. Em integrações assíncronas, um erro posterior pode ser melhor tratado por consulta de estado, callback ou reprocessamento controlado.