Solução de problemas técnicos

Introdução

Mesmo APIs bem documentadas e robustas podem apresentar desafios inesperados durante a integração. Desde problemas de autenticação até lidar com limites de taxa e analisar respostas complexas, esses obstáculos comuns podem atrasar o desenvolvimento e complicar as implantações em produção. As dicas de solução de problemas a seguir visam ajudá-lo a identificar padrões de erro comuns, entender suas causas principais e aplicar soluções práticas, permitindo que você construa aplicativos confiáveis com base na API.

Problemas mais comuns com APIs REST

Esta seção descreve problemas comuns que você pode encontrar ao usar a API e fornece orientações sobre como resolvê-los. Se você continuar enfrentando problemas após tentar essas soluções, considere entrar em contato com nossa equipe de suporte.

Erros de autenticação

Sintomas:

• Recebendo uma resposta HTTP 401 (Não autorizado) ou 403 (Proibido).
• Respostas indicando "Token inválido" ou "Token expirado".

Possíveis causas:

• Cabeçalho de autorização omitido ou malformado.
• Token de acesso expirado ou inválido.
• Credenciais incorretas ou nomes de campos incorretos nos dados do formulário ao chamar o endpoint /login.

Soluções:

• Certifique-se de incluir o Bearer access_token no cabeçalho de autorização para endpoints protegidos.
• Os JSON Web Tokens (JWTs) gerados pela API têm um tempo de vida limitado. Se o token estiver expirado, solicite um novo token via /login usando credenciais válidas.
• Verifique se seu username e password estão corretos e não foram alterados ou revogados.

Payloads de requisição inválidos ou malformados

Sintomas:

• Recebendo um erro HTTP 400 (Requisição inválida).
• Mensagens de erro relacionadas a JSON malformado ou campos obrigatórios ausentes.

Possíveis causas:

• Payload JSON não formatado corretamente (por exemplo, falta de chaves ou vírgulas).
• Parâmetros obrigatórios não incluídos.
• Tipo de conteúdo não JSON nos cabeçalhos da requisição.

Soluções:

• Use um validador de JSON antes de fazer a requisição para verificar a sintaxe do JSON.
• Consulte a documentação do endpoint para garantir que todos os campos obrigatórios (por exemplo, media, bodySite) estejam presentes.
• Inclua Content-Type: application/json no cabeçalho da requisição para os serviços clínicos.

Upload de imagens e problemas de qualidade da imagem

Sintomas:

• Recebendo respostas HTTP 400 ou 422 (Entidade não processável) indicando dados ou formato de imagem inválidos.
• Resultados inconsistentes ou inesperados do /diagnosis-support ou /severity-assessment.

Possíveis causas:

• Formatos de imagem não suportados (apenas imagens codificadas em Base64 são suportadas).
• O arquivo de imagem está corrompido ou incompleto.
• Qualidade da imagem ruim, resultando em baixa confiança dos modelos de visão computacional clínica.
• Imagens não dermatológicas enviadas para serviços que esperam conteúdo dermatológico.

Soluções:

• Confirme se a imagem está codificada em Base64 e usa um formato de arquivo suportado, como JPEG ou PNG.
• Verifique se o arquivo de imagem não está corrompido e se os dados da imagem estão corretamente codificados.
• Use imagens de maior resolução, sem desfoque, com boa iluminação e foco.
• Certifique-se de que a imagem é de natureza dermatológica. Imagens não dermatológicas podem fazer com que o modelo de domínio do dispositivo retorne resultados com alta incerteza.

Resultados pouco claros ou inesperados

Sintomas:

• Distribuição inesperada de possíveis categorias ICD-11, sinais visuais previstos ou máscaras, ou pontuações de sistemas de pontuação automática.
• Resultados que diferem significativamente da expectativa clínica.

Possíveis causas:

• A imagem de entrada pode não mostrar claramente a condição da pele relevante.
• A confiança do modelo em identificar certas condições pode ser baixa devido a imagens ambíguas (por exemplo, imagens mostrando mais de um distúrbio da pele).
• A geração de resultados clínicos depende de múltiplos modelos; se os modelos a montante (por exemplo, domínio ou qualidade) produzirem saídas incertas, as interpretações clínicas a jusante podem ser afetadas.

Soluções:

• Forneça imagens que mostrem claramente a área afetada da pele, de preferência com iluminação e foco adequados.
• Revise a documentação para confirmar que a condição submetida está dentro do conjunto de condições suportadas pelos endpoints /diagnosis-support ou /severity-assessment.
• Se possível, forneça ângulos adicionais da imagem ou condições de captura aprimoradas para ajudar o modelo a performar com mais precisão.

Problemas de rede e desempenho

Sintomas:

• API não é acessível.
• Tempos de resposta lentos ou timeouts de requisição.
• Erros intermitentes de conectividade ou indisponibilidade do servidor (por exemplo, HTTP 502 ou 503).

Possíveis causas:

• Bloqueios de DNS ou firewall.
• Erros inesperados na lógica do servidor.
• Downtime temporário do servidor ou manutenção.
• Alta carga no servidor.
• Conexão de rede ruim do lado do cliente.
• Tamanhos de imagem grandes causando aumento no tempo de processamento.

Soluções:

• Verifique a página de status da API (se disponível) ou entre em contato com o suporte para ver se há manutenção em andamento ou uma interrupção de serviço conhecida.
• Verifique se suas configurações de rede ou firewall permitem requisições de saída para o domínio web da API.
• Se encontrar problemas temporários no servidor, aguarde alguns minutos antes de tentar novamente.
• Reduza o tamanho do arquivo de imagem (sem comprometer a clareza) para melhorar os tempos de processamento. O desempenho permanecerá inalterado, pois nossos modelos de visão computacional são projetados para trabalhar com imagens de qualidade média.
• Certifique-se de que seu cliente tenha uma conexão estável com a internet e considere ajustar os timeouts de requisição.

Limitação de taxa

Sintomas:

• Recebendo respostas HTTP 429 (Muitas requisições).
• Incapacidade temporária repentina de acessar endpoints protegidos, mesmo com autenticação válida.

Possíveis causas:

• Excedendo o limite de requisições permitido dentro de uma determinada janela de tempo.
• Enviando várias requisições rapidamente ou realizando operações em massa sem o devido espaçamento.

Soluções:

• Ao receber um erro 429, aguarde a duração especificada no cabeçalho Retry-After antes de enviar outra requisição. Se esse cabeçalho não estiver presente, aguarde alguns segundos e tente novamente.
• Sempre que possível, agende ou agrupe requisições para evitar enviar muitas em um curto intervalo.
• Consulte os limites de taxa declarados pela API e ajuste seu uso para permanecer dentro das cotas permitidas.
• Armazene em cache informações estáticas ou que mudam raramente para minimizar chamadas de API repetidas.

URLs incorretas, desativações de endpoint ou incompatibilidades de versão

Sintomas:

• Recebendo um erro HTTP 404 (Não encontrado).
• Erros inesperados após uma atualização recente da API ou lançamento de versão.
• Erros indicando que certos parâmetros ou endpoints não são reconhecidos.

Possíveis causas:

• Erros de digitação na URL.
• Uso de endpoints ou parâmetros obsoletos.
• Não seguir a documentação ou diretrizes de versão mais recentes da API.

Soluções:

• Confirme se a URL base e/ou segmentos de caminho correspondem exatamente à documentação. Além disso, verifique se você está usando o verbo HTTP correto (GET ou POST).
• Verifique se você está usando as URLs de endpoint mais recentes e os esquemas de dados para o corpo da requisição.
• Se os endpoints foram desativados, atualize seu aplicativo cliente para usar as alternativas recomendadas.
• Verifique os registros de alterações ou notas de lançamento para obter detalhes sobre comportamentos ou campos de dados atualizados.

Precisa de mais assistência?

Se essas soluções acima não resolverem seu problema e você quiser entrar em contato conosco, acesse a seção Precisa de suporte?.