Erros e novas tentativas
Tente novamente falhas temporárias e corrija erros de solicitação antes de reenviar.
Se uma chamada falhar, salve status HTTP, corpo do erro sem dados sensíveis, horário, endpoint, Model ID e qualquer identificador disponível antes de decidir se tentará novamente.
Erros comuns
| Resultado | O que verificar primeiro | Tentar novamente imediatamente? |
|---|---|---|
400 solicitação inválida | JSON, Model ID, tipos de campos e suporte do modelo | Não; corrija a solicitação |
401 falha de autenticação | Chave de API, formato Bearer e status da credencial | Não; corrija a credencial |
403 acesso restrito | Conta, escopo de modelos, região ou restrições de origem | Não; confirme o acesso |
404 caminho ou recurso ausente | Endereço da API, endpoint, Model ID ou identificador da tarefa | Não; revise a configuração |
429 solicitações em excesso | Taxa, concorrência e orientações de limite retornadas | Tente novamente um número limitado de vezes com taxa menor |
5xx erro de serviço | Request ID e se a solicitação original foi executada | Tente novamente um número limitado de vezes conforme o erro |
| Timeout ou interrupção de conexão | Rede, timeout do cliente e status da solicitação | Não repita às cegas |
| Saldo ou orçamento insuficiente | Saldo disponível, orçamento da chave e proteção de custos | Resolva a restrição primeiro |
Considere a resposta real da API como referência definitiva para corpos de erro e códigos de status.
Configure novas tentativas
Tente novamente apenas erros que possam se recuperar e limite as tentativas e o tempo total de espera. Siga as orientações explícitas de nova tentativa na resposta, quando disponíveis.
Exemplo: tente novamente até 3 vezes, espere cerca de 1, 2 e 4 segundos e adicione um pequeno atraso aleatório.Este é um exemplo de estratégia da aplicação. Ele não garante que um limite da plataforma termine nesses momentos. Não ative tentativas ilimitadas ao mesmo tempo no SDK, na aplicação e no gateway.
Evite solicitações duplicadas
Após um timeout do cliente, verifique a solicitação original em Logs de API. Para imagens ou tarefas longas, confira o identificador existente antes de enviar novamente. Use um campo ou cabeçalho de idempotência apenas quando a interface oferecer suporte explícito.
Contate o suporte
Forneça Request ID, horário e fuso, Model ID, endpoint, status HTTP, erro sem dados sensíveis e etapas de diagnóstico já realizadas. Nunca envie senha, código de verificação, chave de API completa ou conteúdo sensível sem relação com o problema.