Código de motivo estável
Um código de erro estável é usado na lógica do cliente, nos relatórios e no roteamento automático de solicitações.
Documentação / Erros de API
Tratamento de erros de API
Um modelo unificado para respostas, códigos de erro, falhas temporárias, resultados desconhecidos, diagnóstico e recuperação segura em integrações de iGaming.
HTTP
resultado da requisição
Códigos
motivo claro
Nova tentativa
ação segura
Rastreamento
diagnóstico da requisição
Ciclo de tratamento de erros
Da resposta da API à recuperação
01
Determinar o tipo de resultado
Verificar o status HTTP, o código do motivo, a categoria do erro e o estado da operação.
02
Salvar dados para investigação
Registrar os identificadores da requisição e da operação, o endpoint, o horário, a referência do provedor e parâmetros seguros.
03
Escolher uma ação segura
Corrigir os dados, interromper a operação, tentar novamente após uma pausa ou verificar o estado atual.
04
Recuperar e verificar
Evitar duplicidades, reconciliar resultados, notificar as equipes responsáveis e encerrar a causa raiz.
Visão geral
Um erro deve explicar a causa e a próxima ação
Uma resposta HTTP 400 ou 500, sozinha, não é suficiente. Uma API confiável retorna um código de motivo estável, vincula a resposta a um identificador de requisição e deixa claro se é necessário corrigir os dados, interromper a operação, repetir a requisição ou verificar seu estado separadamente.
Ação previsível
A categoria do erro indica se a requisição pode ser repetida e quais dados precisam ser alterados.
Correlação para diagnóstico
Os identificadores de requisição, operação e provedor conectam os logs do cliente aos sistemas internos e ao suporte.
Estrutura do erro
Estrutura recomendada de resposta de erro
A resposta deve ser compacta, estável e adequada ao processamento automatizado, sem expor a implementação interna ou dados sensíveis.
Código de erro
Um identificador estável do motivo, que não muda quando a mensagem explicativa é editada.
Descrição
Uma explicação breve e segura, sem código interno, consultas ao banco de dados, segredos ou detalhes desnecessários.
ID da requisição
Um identificador único para localizar a operação nos logs e acionar o suporte.
Dados adicionais
Um status permitido, limite, estado atual ou motivo seguro para a rejeição.
Pode ser repetida
Uma indicação explícita de erro temporário que não elimina a proteção contra duplicidades da operação.
Pausa antes da nova tentativa
Uma espera recomendada em segundos ou um cabeçalho HTTP para limitação de requisições e indisponibilidade temporária.
Erros de campos
Uma lista de campos problemáticos com código do motivo, caminho do valor e explicação segura.
Referência da documentação
Um link permanente ou identificador de seção que descreve a causa e como corrigi-la.
Categorias de erros
Principais categorias de erros
O status HTTP indica a classe geral do resultado, enquanto o código interno identifica a causa específica e a ação permitida.
Erro de validação de entrada
Formato inválido, campo obrigatório ausente, valor não suportado, precisão incorreta do valor ou estrutura de requisição inválida.
Erro de autenticação
Token, chave de API, assinatura, horário da requisição ou nonce ausente, expirado ou inválido.
Permissões insuficientes
O cliente é reconhecido, mas não possui a função, marca, mercado ou permissão necessária para a ação.
Objeto não encontrado
Um jogador, pagamento, rodada, verificação KYC, provedor ou outro objeto não existe ou não está disponível para o cliente.
Conflito de estado
A versão ou o estado do objeto mudou, ou o identificador da operação já foi usado com parâmetros diferentes.
Violação de regra de negócio
Saldo insuficiente, limite excedido, jogador bloqueado, mercado proibido ou transição de status inválida.
Muitas requisições
O número permitido de requisições para o cliente, método, função ou operação crítica foi excedido.
Provedor indisponível
O serviço externo está indisponível, responde lentamente ou está temporariamente sem aceitar operações.
Erro interno
Um erro inesperado da plataforma, sem exposição de detalhes internos, mas com um identificador para diagnóstico.
Novas tentativas e recuperação
Nova tentativa e resultado desconhecido
Uma nova tentativa só é segura depois de identificar o tipo de erro e verificar se a operação original pode já ter sido concluída.
01
Verificar se a nova tentativa é permitida
Erros de dados, permissão e regras de negócio geralmente exigem correção da requisição, e não um novo envio.
02
Manter a mesma chave da operação
Repetir uma operação financeira, de jogo ou outra operação crítica não deve criar um novo resultado.
03
Aumentar a pausa entre as tentativas
Os intervalos aumentam progressivamente, respeitam o tempo informado pelo servidor e limitam o número total de tentativas.
04
Interromper e encaminhar para análise
Depois que todas as tentativas se esgotam, a operação é registrada como incompleta e encaminhada para análise manual ou conciliação.
Ausência de resposta não significa falha da operação
Se a conexão cair depois que uma requisição for enviada, o resultado pode permanecer desconhecido. Antes de repetir, verifique o estado pelo identificador da operação ou aguarde uma notificação confiável.
Diagnóstico e controle
Logs, identificadores, métricas e alertas
O diagnóstico deve reconstruir o caminho da requisição entre a plataforma, o adaptador e o provedor externo sem armazenar dados sensíveis desnecessários.
Contexto para investigação
Identificadores de requisição, correlação, operação e provedor externo.
Endpoint, método HTTP, ambiente, cliente, horário e duração da resposta.
Status HTTP, código de erro, número de tentativas e estado final.
Campos sensíveis mascarados, cabeçalhos seguros e resultado da validação da assinatura.
Monitoramento e alertas
Taxa de erros por método, provedor, cliente e categoria do motivo.
Aumento de respostas lentas, erros HTTP 5xx, assinaturas inválidas e eventos de limitação de requisições.
Número de novas tentativas, operações com resultado desconhecido e tarefas de recuperação.
Alertas com limites, responsáveis e regras de escalonamento.
Testes
O que testar no ambiente de teste
O ambiente de teste deve reproduzir cada categoria importante de erro e confirmar o comportamento correto do cliente, das novas tentativas e dos controles.
Erros de validação de entrada
Campos ausentes, tipos inválidos, valores não suportados, precisão do valor e vários erros simultâneos.
Acesso e permissões
Chave inválida, token expirado, assinatura incorreta, função não autorizada, IP bloqueado e nonce reutilizado.
Sem resposta e resultado desconhecido
Falha de conexão antes do envio, depois que a operação é aceita e durante o recebimento da resposta final.
Limitação de requisições
HTTP 429, espera recomendada, requisições simultâneas e recuperação após o fim do limite.
Erros do provedor
Indisponibilidade, manutenção, resposta inválida, notificação atrasada e status conflitante.
Nova tentativa e interrupção de proteção
Limitar o número de tentativas, aumentar os intervalos, interromper temporariamente as requisições, realizar recuperação controlada e encaminhar manualmente.
Checklist antes do lançamento
Uma integração de produção é lançada após validar a estrutura de erros, o comportamento do cliente, a proteção contra duplicidades e o diagnóstico.
Todos os erros retornam um código de motivo estável e um identificador de requisição.
Os detalhes dos erros não expõem segredos nem a implementação interna.
As categorias de erros temporários e permanentes estão documentadas.
Uma operação crítica repetida usa a mesma chave de idempotência.
Um resultado desconhecido é tratado pela verificação de estado ou pelo recebimento de uma notificação confiável.
Logs, métricas, alertas, fila de recuperação e regras de escalonamento estão configurados.
Precisa padronizar os erros da API?
Envie suas respostas HTTP atuais, códigos de erro, regras de nova tentativa e cenários problemáticos. A APIACE ajudará a definir um modelo unificado de erros, recuperação segura e abordagem de controle.