Código de motivo estável
Um código de erro estável é usado na lógica do cliente, nos relatórios e no encaminhamento automático de pedidos.
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 do pedido
Códigos
motivo claro
Nova tentativa
ação segura
Rastreio
diagnóstico do pedido
Ciclo de tratamento de erros
Da resposta da API à recuperação
01
Determinar o tipo de resultado
Verificar o estado HTTP, o código do motivo, a categoria do erro e o estado da operação.
02
Guardar dados para investigação
Registar os identificadores do pedido e da operação, o endpoint, o horário, a referência do fornecedor 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 equipas 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, por si só, não é suficiente. Uma API fiável devolve um código de motivo estável, associa a resposta a um identificador de pedido e permite perceber se é necessário corrigir os dados, interromper a operação, repetir o pedido ou verificar separadamente o respetivo estado.
Ação previsível
A categoria do erro indica se o pedido pode ser repetido e quais os dados que têm de ser alterados.
Correlação para diagnóstico
Os identificadores de pedido, operação e fornecedor ligam 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 base de dados, segredos ou detalhes desnecessários.
ID do pedido
Um identificador único para localizar a operação nos logs e acionar o suporte.
Dados adicionais
Um estado 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 pedidos 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 secção que descreve a causa e como corrigi-la.
Categorias de erros
Principais categorias de erros
O estado 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 pedido inválido.
Erro de autenticação
Token, chave de API, assinatura, horário do pedido 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, ronda, verificação KYC, fornecedor 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 estado inválida.
Muitos pedidos
O número permitido de pedidos para o cliente, método, função ou operação crítica foi excedido.
Fornecedor 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 do pedido, 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 indicado pelo servidor e limitam o número total de tentativas.
04
Interromper e encaminhar para análise
Depois de esgotadas todas as tentativas, a operação é registada como incompleta e encaminhada para análise manual ou reconciliação.
Ausência de resposta não significa falha da operação
Se a ligação cair depois de um pedido ter sido enviado, o resultado pode permanecer desconhecido. Antes de repetir, verifique o estado através do identificador da operação ou aguarde uma notificação fiável.
Diagnóstico e controlo
Logs, identificadores, métricas e alertas
O diagnóstico deve reconstruir o caminho do pedido entre a plataforma, o adaptador e o fornecedor externo sem armazenar dados sensíveis desnecessários.
Contexto para investigação
Identificadores de pedido, correlação, operação e fornecedor externo.
Endpoint, método HTTP, ambiente, cliente, horário e duração da resposta.
Estado 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.
Monitorização e alertas
Taxa de erros por método, fornecedor, cliente e categoria do motivo.
Aumento de respostas lentas, erros HTTP 5xx, assinaturas inválidas e eventos de limitação de pedidos.
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 controlos.
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 ligação antes do envio, depois de a operação ser aceite e durante a receção da resposta final.
Limitação de pedidos
HTTP 429, espera recomendada, pedidos simultâneos e recuperação após o fim do limite.
Erros do fornecedor
Indisponibilidade, manutenção, resposta inválida, notificação atrasada e estado conflitante.
Nova tentativa e interrupção de proteção
Limitar o número de tentativas, aumentar os intervalos, interromper temporariamente os pedidos, realizar recuperação controlada e encaminhar manualmente.
Lista de verificação 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 devolvem um código de motivo estável e um identificador de pedido.
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 pela receção de uma notificação fiável.
Logs, métricas, alertas, fila de recuperação e regras de escalonamento estão configurados.
Precisa de normalizar os erros da API?
Envie as 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 controlo.