Tratamento de Erros

A API da Alloyal utiliza códigos de status HTTP padrão para comunicar o resultado das requisições. Em caso de falha, as respostas incluem detalhes adicionais em formato JSON para facilitar a identificação e solução do problema.

Confira o formato típico de uma resposta de erro:

code: Representa o código do erro em formato legível para desenvolvedores.
message: Fornece uma descrição detalhada do erro ocorrido.
details: Inclui informações adicionais relevantes para solucionar o problema, quando aplicável.

Aqui estão os códigos de status mais comuns retornados pela API, com descrições claras:

200 OK: A requisição foi bem-sucedida e o servidor retornou o resultado esperado.
201 Created: O recurso foi criado com sucesso (ex.: novo usuário ou transação).

400 Bad Request:
Causa: Dados enviados na requisição são inválidos ou estão ausentes.
Como corrigir: Verifique o formato da requisição e os campos obrigatórios.
401 Unauthorized:
Causa: Falha na autenticação ou ausência de credenciais válidas.
Como corrigir: Confirme se o token de acesso e outros headers estão configurados corretamente.
403 Forbidden:
Causa: O cliente não tem permissão para acessar o recurso solicitado.
Como corrigir: Verifique as permissões de acesso da sua conta ou aplicação.
404 Not Found:
Causa: O recurso solicitado não existe ou o endpoint está incorreto.
Como corrigir: Certifique-se de que o caminho da URL e os parâmetros estão corretos.
429 Too Many Requests:
Causa: O cliente ultrapassou o limite de requisições permitido em um período.
Como corrigir: Aguarde ou ajuste sua aplicação para respeitar o rate limit da API.

500 Internal Server Error:
Causa: Ocorreu um erro inesperado no servidor.
Como corrigir: Relate o problema ao suporte técnico com detalhes da requisição feita.

Valide os dados antes de enviar: Certifique-se de que todos os campos obrigatórios estão preenchidos.
Revise as permissões de acesso: Garanta que sua aplicação tem as credenciais adequadas.
Respeite o rate limit: Implante estratégias de retry/backoff em caso de limite atingido.
Mantenha a documentação por perto: Consulte o guia da API para detalhes atualizados.