Solución de problemas técnicos

Introducción

Incluso las API bien documentadas y robustas pueden presentar desafíos inesperados durante la integración. Desde problemas de autenticación hasta el manejo de límites de velocidad y la interpretación de respuestas complejas, estos obstáculos comunes pueden ralentizar el desarrollo y complicar los despliegues en producción. Los siguientes consejos de solución de problemas tienen como objetivo ayudarle a identificar patrones de error comunes, comprender sus causas raíz y aplicar soluciones prácticas, permitiéndole construir aplicaciones confiables sobre la API.

Problemas más comunes con la API REST

Esta sección describe los problemas comunes que puede encontrar al utilizar la API y proporciona orientación sobre cómo resolverlos. Si continúa experimentando problemas después de intentar estas soluciones, considere ponerse en contacto con nuestro equipo de soporte.

Errores de autenticación

Síntomas:

• Recibir una respuesta HTTP 401 (No autorizado) o 403 (Prohibido).
• Respuestas que indican "Token inválido" o "Token expirado".

Posibles causas:

• Encabezado de autorización omitido o mal formado.
• Token de acceso expirado o inválido.
• Credenciales incorrectas o nombres de campos incorrectos en los datos del formulario al llamar al endpoint /login.

Soluciones:

• Asegúrese de haber incluido el Bearer access_token en el encabezado de autorización para los endpoints protegidos.
• Los JSON Web Tokens (JWT) generados por la API tienen una vida útil limitada. Si el token ha expirado, solicite un nuevo token a través de /login utilizando credenciales válidas.
• Verifique que su username y password sean correctos y no hayan sido cambiados o revocados.

Solicitudes de carga útil inválidas o mal formadas

Síntomas:

• Recibir un error HTTP 400 (Solicitud incorrecta).
• Mensajes de error relacionados con JSON mal formado o campos obligatorios faltantes.

Posibles causas:

• La carga útil JSON no está correctamente formateada (por ejemplo, faltan llaves o comas).
• Parámetros obligatorios no incluidos.
• Tipo de contenido no JSON en los encabezados de la solicitud.

Soluciones:

• Utilice un validador JSON antes de realizar la solicitud para verificar la sintaxis JSON.
• Consulte la documentación del endpoint para asegurarse de que todos los campos obligatorios (por ejemplo, media, bodySite) estén presentes.
• Incluya Content-Type: application/json en el encabezado de la solicitud para los servicios clínicos.

Problemas de carga de imágenes y calidad

Síntomas:

• Recibir respuestas HTTP 400 o 422 (Entidad no procesable) que indican datos o formato de imagen inválidos.
• Resultados inconsistentes o inesperados de /diagnosis-support o /severity-assessment.

Posibles causas:

• Formatos de imagen no admitidos (solo se admiten imágenes codificadas en Base64).
• El archivo de imagen está dañado o incompleto.
• Calidad de imagen deficiente que resulta en baja confianza por parte de los modelos de visión por computadora clínica.
• Imágenes no dermatológicas enviadas a servicios que esperan contenido dermatológico.

Soluciones:

• Confirme que la imagen esté codificada en Base64 y utilice un formato de archivo compatible, como JPEG o PNG.
• Verifique que el archivo de imagen no esté dañado y que los datos de la imagen estén correctamente codificados.
• Utilice imágenes de mayor resolución sin borrosidad, con buena iluminación y enfoque.
• Asegúrese de que la imagen sea de naturaleza dermatológica. Las imágenes no dermatológicas pueden hacer que el modelo de dominio del dispositivo devuelva resultados de alta incertidumbre.

Resultados poco claros o inesperados

Síntomas:

• Distribución inesperada de posibles categorías ICD-11, signos visuales predichos o máscaras, o puntajes de sistemas de puntuación automática.
• Resultados que difieren significativamente de la expectativa clínica.

Posibles causas:

• La imagen de entrada puede no mostrar claramente la afección cutánea relevante.
• La confianza del modelo en la identificación de ciertas condiciones puede ser baja debido a imágenes ambiguas (por ejemplo, imágenes que muestran más de un trastorno de la piel).
• La generación de resultados clínicos depende de múltiples modelos; si los modelos ascendentes (por ejemplo, dominio o calidad) producen salidas inciertas, las interpretaciones clínicas descendentes pueden verse afectadas.

Soluciones:

• Proporcione imágenes que muestren claramente el área afectada de la piel, preferiblemente con la iluminación y el enfoque adecuados.
• Revise la documentación para confirmar que la condición enviada esté dentro del conjunto de condiciones admitidas para los endpoints /diagnosis-support o /severity-assessment.
• Si es posible, proporcione ángulos de imagen adicionales o condiciones de captura mejoradas para ayudar al modelo a desempeñarse con más precisión.

Problemas de red y rendimiento

Síntomas:

• La API no es accesible.
• Tiempos de respuesta lentos o tiempos de espera de solicitud.
• Errores intermitentes de conectividad o indisponibilidad del servidor (por ejemplo, HTTP 502 o 503).

Posibles causas:

• Bloqueos de DNS o firewall.
• Errores inesperados en la lógica del servidor.
• Tiempo de inactividad temporal del servidor o mantenimiento.
• Alta carga del servidor.
• Mala conexión de red en el lado del cliente.
• Tamaños de imagen grandes que provocan un aumento en el tiempo de procesamiento.

Soluciones:

• Verifique la página de estado de la API (si está disponible) o comuníquese con el soporte para ver si hay mantenimiento en curso o una interrupción del servicio conocida.
• Verifique si su configuración de red o firewall permite solicitudes salientes al dominio web de la API.
• Si encuentra problemas temporales en el servidor, espere unos minutos antes de volver a intentarlo.
• Reduzca el tamaño del archivo de imagen (sin comprometer la claridad) para mejorar los tiempos de procesamiento. El rendimiento no se verá afectado, ya que nuestros modelos de visión por computadora están diseñados para trabajar con imágenes de calidad media.
• Asegúrese de que su cliente tenga una conexión a internet estable y considere ajustar los tiempos de espera de las solicitudes.

Límite de tasa

Síntomas:

• Recibir respuestas HTTP 429 (Demasiadas solicitudes).
• Imposibilidad temporal repentina de acceder a endpoints protegidos incluso con autenticación válida.

Posibles causas:

• Exceder el límite de solicitudes permitido dentro de una determinada ventana de tiempo.
• Envío rápido de múltiples solicitudes o realización de operaciones masivas sin el ritmo adecuado.

Soluciones:

• Al recibir un error 429, espere la duración especificada en el encabezado Retry-After antes de enviar otra solicitud. Si este encabezado no está presente, espere unos segundos y vuelva a intentar la solicitud.
• Siempre que sea posible, programe o agrupe solicitudes para evitar enviar muchas en un corto intervalo de tiempo.
• Consulte los límites de tasa establecidos por la API y ajuste su uso para mantenerse dentro de las cuotas permitidas.
• Almacene en caché información estática o que cambia raramente para minimizar las llamadas repetidas a la API.

URLs incorrectas, deprecaciones de endpoints o incompatibilidades de versión

Síntomas:

• Recibir un error HTTP 404 (No encontrado).
• Errores inesperados después de una actualización reciente de la API o lanzamiento de versión.
• Errores que indican que ciertos parámetros o endpoints no son reconocidos.

Posibles causas:

• Errores tipográficos en la URL.
• Uso de endpoints o parámetros obsoletos.
• No seguir la documentación o las pautas de versión más recientes de la API.

Soluciones:

• Confirme que la URL base y/o los segmentos de ruta coincidan exactamente con la documentación. Además, verifique que esté utilizando el verbo HTTP correcto (GET o POST).
• Verifique que esté utilizando las últimas URL de endpoints y esquemas de datos para el cuerpo de la solicitud.
• Si los endpoints han sido desaprobados, actualice su aplicación cliente para utilizar las alternativas recomendadas.
• Consulte los registros de cambios o notas de la versión para obtener detalles sobre comportamientos o campos de datos actualizados.

¿Necesita más ayuda?

Si estas soluciones anteriores no resuelven su problema y desea comunicarse con nosotros, diríjase a la sección ¿Necesita soporte?.