Guia de Solução de Problemas

Este guia ajuda-o a resolver problemas comuns ao trabalhar com a API do XD Soba.

Problemas Comuns

Erros de Autenticação

401 Não Autorizado

• Verifique se o seu token é válido e não expirou
• Confirme o formato do token: Bearer o_seu_token_aqui
• Certifique-se de que está a utilizar as credenciais corretas

403 Proibido

• Verifique se a sua conta possui as permissões necessárias
• Confirme se a sua chave de API está ativa
• Contacte o suporte se necessitar de acesso a endpoints específicos

Erros de Recurso

404 Recurso não encontrado

• Verifique se o URL do endpoint está correto
• Confirme se o ID do recurso existe
• Certifique-se de que o recurso não foi eliminado

Limitação de Pedidos

429 Demasiados Pedidos

• Verifique os cabeçalhos de limite de pedidos na resposta
• Implemente um recuo exponencial na sua lógica de tentativas
• Considere implementar cache para reduzir as chamadas à API

Erros de Validação

400 Pedido Inválido

• Verifique se todos os campos obrigatórios estão presentes
• Confirme os tipos de dados e formatos
• Certifique-se de que os formatos de data estão corretos (ISO 8601)
• Valide os comprimentos de texto e os intervalos numéricos

Erros de Servidor

500 Erro Interno do Servidor

• Este é um erro do lado do servidor — tente novamente após alguns segundos
• Se o erro persistir, contacte o suporte
• Inclua o valor do cabeçalho X-Request-ID ao reportar o problema

Códigos de Erro

Código	Descrição	Solução
AUTH_001	Credenciais inválidas	Verifique o nome de utilizador e a palavra-passe
AUTH_002	Token expirado	Solicite um novo token
AUTH_003	Formato de token inválido	Assegure o formato correto do Bearer token
VAL_001	Campo obrigatório em falta	Verifique o payload do pedido
VAL_002	Tipo de dados inválido	Confirme os tipos dos campos
VAL_003	Valor fora do intervalo	Verifique os limites numéricos
RES_001	Recurso não encontrado	Verifique o URL do endpoint e o ID do recurso
RATE_001	Limite de pedidos excedido	Implemente uma estratégia de recuo
PERM_001	Permissões insuficientes	Contacte o suporte
SRV_001	Erro interno do servidor	Tente novamente ou contacte o suporte

Dicas de Depuração

Registo de Pedidos

Ative o registo de pedidos na sua aplicação:

// Exemplo em C#
var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Debug", "true");

Cabeçalhos de Resposta

Verifique estes cabeçalhos para obter informações adicionais:

• X-Request-ID: Para rastreamento de pedidos
• X-RateLimit-*: Para informações sobre limites de pedidos
• X-Error-Code: Para códigos de erro detalhados

Soluções Comuns

1. Problemas com Tokens

   # Verificar o formato do token
   curl -X GET "https://api.xdsoba.com/gateway/your-endpoint" \
        -H "Authorization: Bearer o_seu_token_aqui" \
        -v

2. Limitação de Pedidos

   # Verificar os cabeçalhos de limite de pedidos
   curl -X GET "https://api.xdsoba.com/gateway/your-endpoint" \
        -H "Authorization: Bearer o_seu_token_aqui" \
        -I

3. Erros de Validação

   # Testar com payload mínimo
   curl -X POST "https://api.xdsoba.com/gateway/your-endpoint" \
        -H "Content-Type: application/json" \
        -d '{"campo_obrigatorio": "valor"}'

Obter Ajuda

Se continuar a ter problemas:

1. Consultar a Documentação
   • Reveja o Guia de Introdução
   • Leia o Guia de Utilização da API
   • Consulte a Referência da API