Error de autenticación de la API de seguimiento: 7 causas de las respuestas 401/403 y cómo solucionarlas
Un error de autenticación de una API de seguimiento suele deberse a una de estas siete causas: falta de credenciales, un encabezado de autenticación con formato incorrecto, un secreto no válido o revocado, una discrepancia de entorno, permisos insuficientes, un token caducado o una firma no válida, o una regla de seguridad que bloquea la solicitud. Para corregir una respuesta 401 o 403, identifica primero qué sistema la devolvió y, después, comprueba la solicitud según los requisitos de autenticación del proveedor. Repetir los intentos sin cambiar las credenciales rara vez resuelve el problema subyacente.

Esta guía está dirigida a desarrolladores y equipos de integración que conectan el seguimiento de envíos con una plataforma de comercio electrónico, un sistema de gestión de pedidos, una aplicación de almacén o un panel interno. Comienza con una solicitud que falle en lugar de cambiar las credenciales de toda la integración.
Primero, distingue entre 401 y 403
Las definiciones HTTP ofrecen un punto de partida, no un diagnóstico completo. 401 Unauthorized significa que la solicitud no contiene credenciales de autenticación válidas para el recurso de destino. 403 Forbidden significa que el servidor entendió la solicitud, pero se niega a cumplirla. Un 403 no demuestra necesariamente que la autenticación haya sido correcta: una puerta de enlace o un servicio de seguridad puede rechazar una solicitud antes de que la aplicación evalúe sus credenciales.
Según RFC 9110, un servidor que genera una respuesta 401 debe incluir un desafío WWW-Authenticate. Inspecciona ese encabezado cuando esté presente, pero lee también el cuerpo de la respuesta y la documentación de errores del proveedor. Las implementaciones no siempre muestran los errores de la misma manera.
| Lo que observas | Qué investigar primero |
|---|---|
| 401 con un mensaje de credencial ausente o no válida | Inyección de credenciales, formato del encabezado y validez de las credenciales |
| 403 con un mensaje de permisos insuficientes | Ámbitos, acceso a la cuenta, inquilino y propiedad del recurso |
| 403 con una página de seguridad HTML | Puerta de enlace, proxy, firewall o política de acceso |
| Éxito HTTP con un error dentro de JSON | Los campos de error a nivel de aplicación del proveedor |
Mantén separados en los registros el estado de transporte y el estado de la aplicación. Un campo JSON llamado code no es automáticamente un estado HTTP, y un intercambio HTTP correcto no significa necesariamente que la operación de seguimiento solicitada haya tenido éxito.
Captura un registro de diagnóstico seguro
Antes de cambiar nada, registra la marca de tiempo UTC, el método HTTP, el nombre de host, la ruta, el estado de la respuesta, el mensaje de error del proveedor, el ID de solicitud y el entorno de despliegue. Indica si la respuesta procedía del proveedor de seguimiento, de tu propio backend o de un intermediario.
Registra los nombres de los encabezados de autenticación y si los valores están presentes, pero nunca registres claves API completas, tokens bearer, tokens de actualización ni secretos de firma. Evita exportar trazas de solicitudes sin redactar. Los números de seguimiento y los detalles de los envíos también pueden requerir redacción según las normas de gestión de datos de tu organización.
Utiliza una operación de bajo impacto documentada por el proveedor para reproducir el problema. No registres envíos repetidamente, crees suscripciones ni cambies la configuración de webhooks solo para probar la autenticación.
7 causas de las respuestas 401/403 de la API de seguimiento
1. La credencial nunca llega a la API
Un secreto puede existir en una consola de despliegue sin estar disponible para la aplicación en ejecución. Entre los puntos de fallo habituales se incluyen una variable de entorno ausente, una referencia incorrecta al secreto, un trabajador que no se reinició después de un cambio de configuración o un generador de solicitudes que omite los valores vacíos.
Un proxy también puede eliminar un encabezado de autenticación. Presta atención a las redirecciones, ya que un cliente HTTP podría no reenviar encabezados confidenciales a un host diferente.
- Comprobar: Inspecciona la solicitud en el último punto de salida confiable. Confirma que el encabezado requerido existe y contiene un valor no vacío.
- Solucionar: Corrige la asignación del secreto o la construcción de la solicitud y vuelve a cargar el proceso afectado si es necesario.
- Verificar: Ejecuta la misma operación desde la aplicación desplegada, no solo desde el portátil de un desarrollador.
Si las solicitudes locales funcionan pero fallan los trabajos en segundo plano, compara primero su configuración de ejecución. La aplicación y sus trabajadores pueden recibir los secretos mediante mecanismos diferentes.
2. El formato de autenticación es incorrecto
Las API de seguimiento no aceptan todas el mismo esquema de autenticación. Un proveedor puede exigir un encabezado de clave API específico, un token bearer de OAuth o una solicitud firmada. Colocar una clave válida en Authorization: Bearer no servirá si el endpoint espera un encabezado diferente.
Otros errores incluyen copiar comillas en un secreto, añadir un prefijo que el proveedor no requiere, enviar encabezados de autenticación duplicados o utilizar un campo de configuración del SDK que corresponde a otro método de autenticación.
- Comprobar: Compara la solicitud real con el ejemplo oficial del endpoint y la versión exactos de la API.
- Solucionar: Coincide con el nombre del encabezado, el formato del valor y el esquema de autenticación documentados. No muevas un secreto a la URL como solución alternativa.
- Verificar: Compara una solicitud mínima con la solicitud generada por el SDK, manteniendo las credenciales redactadas.
Los nombres de los campos de encabezado HTTP no distinguen mayúsculas de minúsculas según la semántica HTTP. Por tanto, cambiar únicamente las mayúsculas no suele ser la solución. Concéntrate en el campo, el valor y la ruta de transmisión correctos.
3. La clave es incorrecta, fue revocada o ya no se ha desplegado de forma coherente
Una clave copiada puede estar incompleta, pertenecer a otra cuenta o haber sido revocada durante un cambio de seguridad. La rotación de credenciales también puede producir fallos intermitentes: algunas instancias de la aplicación utilizan el secreto de reemplazo mientras que otras siguen usando el antiguo.
No asumas que todas las claves API caducan automáticamente. Las reglas de caducidad y rotación dependen del proveedor y del tipo de credencial.
- Comprobar: Confirma el estado de la credencial en la consola de la cuenta autorizada y compara la versión del secreto desplegado en aplicaciones, trabajadores y trabajos programados.
- Solucionar: Despliega una credencial válida mediante tu proceso de gestión de secretos. Si sospechas que se ha expuesto, sigue tu procedimiento de incidentes y revoca la credencial comprometida.
- Verificar: Comprueba cada ruta de ejecución afectada después del despliegue. Una sola solicitud correcta no demuestra que todas las instancias se hayan actualizado.
Cuando sea compatible, utiliza un identificador de credencial no secreto o la versión del gestor de secretos para distinguir los despliegues. Nunca pidas a un cliente o compañero que pegue una clave completa en un ticket de soporte.
4. La credencial y el endpoint pertenecen a entornos diferentes
Algunos servicios separan las credenciales de producción y prueba, los endpoints regionales, las cuentas o los inquilinos. Una credencial válida puede fallar cuando se presenta al host o contexto de cuenta equivocado. Esta comprobación solo se aplica cuando el proveedor documenta dichas distinciones.
Otra posibilidad es una URL base obsoleta. Una integración puede utilizar un endpoint antiguo mientras su configuración de autenticación ya se ha actualizado para una API más reciente.
- Comprobar: Revisa el destino completo: esquema, nombre de host, versión de la API, ruta y cualquier identificador de cuenta o inquilino requerido.
- Solucionar: Asocia la credencial con su entorno y endpoint previstos. Mantén juntas la URL y la configuración de secretos de cada entorno.
- Verificar: Confirma el destino resuelto en el despliegue en ejecución y comprueba si el cliente sigue redirecciones.
Evita probar una lista de hosts adivinados con una credencial real. Utiliza únicamente los endpoints documentados por el proveedor.
5. La autenticación funciona, pero los permisos son insuficientes
Una credencial puede identificar al autor de la llamada sin autorizar la operación solicitada. Leer eventos de envíos, registrar números de seguimiento, cambiar suscripciones y administrar una cuenta pueden requerir derechos de acceso diferentes.
La propiedad del recurso también es importante. Un envío visible en un espacio de trabajo puede no ser accesible mediante una credencial asociada a otro. Algunos sistemas limitan deliberadamente los detalles de los errores, por lo que un 403 por sí solo no puede establecer si existe un recurso.
- Comprobar: Inspecciona los ámbitos, roles, pertenencia a la cuenta, propiedad del recurso y requisitos de acceso específicos del endpoint.
- Solucionar: Concede únicamente el permiso necesario para la integración o utiliza la cuenta autorizada correcta.
- Verificar: Prueba la operación que falla con un recurso que la cuenta tenga permiso conocido para controlar.
Para tokens bearer de OAuth, RFC 6750 distingue entre invalid_token e insufficient_scope. Cuando el proveedor sigue esta convención, el primero apunta a la validez del token y el segundo a la autorización. No asumas que todas las API de seguimiento utilizan OAuth o estos campos de error.
6. Un token ha caducado o la firma de una solicitud no es válida
La autenticación basada en el tiempo añade modos de fallo más allá de una clave estática incorrecta. Un token de acceso OAuth puede caducar. Una solicitud firmada puede rechazarse porque su marca de tiempo queda fuera del intervalo aceptado o porque el servidor calcula una firma diferente.
Las discrepancias de firma pueden deberse a firmar un cuerpo de solicitud y enviar otro, codificar una ruta de forma diferente, cambiar parámetros de consulta o utilizar un secreto de firma incorrecto. Estas comprobaciones solo se aplican a las API que documentan solicitudes firmadas.
- Comprobar: Examina la caducidad del token y los resultados de actualización. Para las firmas, compara la solicitud canónica documentada con los bytes y campos exactos enviados.
- Solucionar: Actualiza u obtiene tokens mediante el flujo compatible, sincroniza la hora del sistema y genera las firmas después de finalizar los componentes de la solicitud firmada.
- Verificar: Prueba durante el siguiente límite de actualización del token, no solo inmediatamente después de obtener uno nuevo.
En sistemas con varios trabajadores, coordina las actualizaciones de tokens para que los trabajadores no sobrescriban repetidamente credenciales utilizables ni inicien actualizaciones simultáneas. Mantén los tokens de actualización protegidos y separados de los registros de solicitudes ordinarios.
7. Una puerta de enlace, un firewall o una política de red bloquea la solicitud
Un 403 puede originarse fuera de la aplicación de seguimiento. Entre las posibles causas se incluyen una discrepancia en la lista de IP permitidas, una política de proxy saliente, una regla de firewall de aplicaciones web o una puerta de enlace de acceso que exige su propia autorización.
Una página de denegación HTML, un encabezado de respuesta desconocido o un ID de solicitud específico de la puerta de enlace pueden ayudar a identificar la capa que rechaza la solicitud. Son indicios, no pruebas; confírmalo con los registros de la puerta de enlace o con el equipo de soporte del proveedor.
- Comprobar: Compara la IP pública de salida y la ruta de red del despliegue que falla con las de un entorno conocido que funcione.
- Solucionar: Corrige la lista de permitidos, la configuración del proxy o la regla de seguridad limitada correspondiente mediante el equipo de infraestructura responsable.
- Verificar: Repite la solicitud desde el entorno de ejecución original después del cambio de política.
No desactives la verificación de certificados TLS ni eludas ampliamente los controles de seguridad. Los fallos de CORS del navegador también requieren un diagnóstico separado: comprueba si la solicitud rechazada es una solicitud previa OPTIONS o la llamada real a la API. Los secretos de larga duración de una API de seguimiento no deben exponerse en código del navegador.
Utiliza una solicitud mínima para aislar el fallo
Reduce la llamada que falla a su endpoint documentado, método, autenticación requerida y carga útil válida más pequeña. Lo siguiente es una plantilla de diagnóstico genérica, no una solicitud funcional específica de un proveedor:
curl --include \
--request "$DOCUMENTED_METHOD" \
--url "$DOCUMENTED_ENDPOINT" \
--header "$DOCUMENTED_AUTH_HEADER: $DOCUMENTED_AUTH_VALUE"Añade el tipo de contenido y el cuerpo requeridos si la operación los necesita. Utiliza esto únicamente en un entorno controlado: los argumentos de comandos, las grabaciones del terminal y las herramientas de diagnóstico pueden exponer secretos. Evita las trazas detalladas salvo que puedas proteger y redactar su salida.
Si la solicitud mínima tiene éxito pero la aplicación falla, inspecciona la configuración del SDK, la construcción de encabezados, las redirecciones, el comportamiento del proxy y los secretos de ejecución. Si ambas fallan, investiga la validez de las credenciales, la selección del endpoint, los permisos y la política de red. Cambia una variable a la vez para que el resultado identifique una causa.
Aplicación de las comprobaciones a una integración con 17TRACK
Para una integración con 17TRACK Tracking API, comienza por la documentación oficial de la API y sigue las instrucciones de autenticación y el formato de solicitud correspondientes a la operación que estás llamando. No sustituyas un patrón de autenticación copiado de una API no relacionada ni asumas que el acceso a una página de seguimiento para consumidores confirma la autorización de la API.
Compara la solicitud documentada con la solicitud que sale de tu servidor y, después, inspecciona tanto la respuesta HTTP como los campos de respuesta documentados. Si es necesario escalar el problema, envía un ejemplo redactado, la marca de tiempo, el endpoint, los detalles de la respuesta y el identificador de solicitud cuando esté disponible. Mantén el secreto de la API fuera del informe.
Deja de repetir intentos a ciegas y confirma la recuperación
Los fallos de autenticación deben activar un diagnóstico, no un bucle de reintentos ilimitado. En el caso de un token explícitamente caducado, puede ser apropiada una actualización controlada seguida de un reintento limitado. En el caso de permisos ausentes, credenciales revocadas o una ruta de red bloqueada, los reintentos no repararán la configuración.
Antes de repetir una operación de escritura, comprueba el comportamiento de idempotencia o gestión de duplicados del proveedor. Esto es importante cuando un intermediario hace que el resultado original sea incierto.
La recuperación se completa cuando la operación prevista tiene éxito desde el despliegue original, todos los trabajadores pertinentes utilizan la configuración correcta y la supervisión no muestra fallos de autenticación continuos. Registra por separado el estado HTTP y los errores a nivel de aplicación, con alertas que identifiquen el endpoint y el entorno afectados sin exponer credenciales.
Preguntas frecuentes
¿Por qué la solicitud funciona localmente, pero falla en producción?
Compara las versiones de los secretos, las URL base, los proxies salientes, las IP de salida, los relojes del sistema y la configuración de ejecución. El éxito local demuestra que funciona una ruta de solicitud; no demuestra que producción envíe la misma solicitud ni tenga los mismos permisos.
¿Debería generar inmediatamente una nueva clave API?
No, a menos que la credencial actual no sea válida, haya sido revocada o pueda haberse expuesto. Primero comprueba si llega al endpoint correcto con el formato requerido. Una rotación innecesaria puede introducir fallos en otros servicios que todavía dependan de la clave existente.
¿Puede un número de seguimiento incorrecto causar un 401 o 403?
Un número de seguimiento no válido normalmente es una cuestión de validación o de nivel de recurso, no una prueba de autenticación no válida. Sin embargo, el acceso a un envío puede estar restringido por la propiedad de la cuenta. Utiliza los detalles de error documentados por el proveedor en lugar de diagnosticar únicamente a partir del número.
¿Significa un 403 que mi suscripción a la API ha caducado?
No. Las restricciones de suscripción o derechos son solo una posibilidad si el proveedor las documenta o devuelve un mensaje específico. Los permisos, el contexto de la cuenta y las políticas de seguridad también pueden causar el rechazo. No deduzcas un problema de facturación únicamente a partir del estado HTTP.
¿Qué debo incluir en una solicitud de soporte?
Incluye la marca de tiempo UTC, el método, el endpoint, el entorno, el estado HTTP, el cuerpo de respuesta redactado, el ID de solicitud y si el problema se reproduce con una solicitud mínima. Describe los despliegues o cambios de credenciales recientes. Excluye los secretos y redacta los datos de envío que no sean necesarios para el diagnóstico.
Fuentes
- RFC 9110: HTTP Semantics — autenticación HTTP, semántica de encabezados y definiciones de 401 y 403.
- RFC 6750: OAuth 2.0 Bearer Token Usage — respuestas de error de tokens bearer, tokens no válidos y ámbitos insuficientes.
- 17TRACK API documentation — referencia específica del proveedor para implementar y solucionar problemas de una solicitud de 17TRACK API.


