Manejo de errores de la API de seguimiento: cómo gestionar números de seguimiento no válidos, límites de solicitudes y reintentos

Gestione los errores de la API de seguimiento separando las entradas no válidas, los fallos temporales, los límites de frecuencia y los resultados del estado del envío. Rechace o corrija los números de seguimiento no válidos en lugar de volver a intentarlos sin cambios, coordine el volumen de solicitudes cuando se alcance un límite y vuelva a intentar los fallos transitorios con un retroceso exponencial acotado y jitter. Antes de repetir un registro u otra solicitud de escritura, determine si el primer intento tuvo éxito.

Para los desarrolladores que conectan datos de seguimiento con un sistema de gestión de pedidos, una plataforma de almacén o una página de seguimiento orientada al cliente, el objetivo no es simplemente reducir las solicitudes fallidas. Se trata de ofrecer una visibilidad fiable de los envíos sin registros duplicados, tormentas de reintentos, mensajes de entrega engañosos ni tickets de soporte innecesarios.

Clasifique el fallo antes de elegir una respuesta

Una integración de seguimiento tiene varios resultados independientes que deben evaluarse: si la solicitud de red se completó, si la API aceptó la operación, si cada elemento de seguimiento solicitado tuvo éxito y si hay eventos del envío disponibles. Tratar los cuatro aspectos como una única marca de éxito o fracaso genera errores evitables.

Una respuesta HTTP exitosa no significa necesariamente que todos los elementos de un lote hayan tenido éxito. Por el contrario, una consulta procesada correctamente sin eventos de seguimiento no es necesariamente un fallo de la API. Inspeccione el cuerpo de la respuesta y aplique el significado documentado por el proveedor para cada resultado.

Condición	Acción recomendada	¿Reintentar sin cambios?
Número mal formado o campo de solicitud no válido	Valide y corrija la entrada	No
Credenciales ausentes o no válidas	Compruebe las credenciales, los permisos y el entorno	No hasta corregirlo
Respuesta de límite de frecuencia	Retrase el trabajo afectado y reduzca la presión compartida de solicitudes	Después de la espera requerida, si es seguro
Fallo temporal del servicio	Aplique un retroceso acotado y compruebe la seguridad de la operación	Normalmente, dentro de un presupuesto de reintentos
Tiempo de espera agotado después de enviar un registro	Compruebe si el registro existe	No a ciegas
Consulta aceptada sin eventos del envío	Siga el ciclo de vida de seguimiento documentado	Utilice una actualización programada, no reintentos rápidos

Los códigos de estado HTTP proporcionan un punto de partida, no un árbol de decisiones completo específico del proveedor. RFC 9110 define la semántica HTTP, mientras que RFC 6585 define 429 Too Many Requests. Su integración también debe interpretar los códigos de error de aplicación documentados y los resultados a nivel de elemento.

Números de seguimiento no válidos: distinga las entradas incorrectas de los eventos ausentes

“Número de seguimiento no válido” puede describir distintos problemas: un identificador mal formado, una combinación de transportista y número no compatible, la ausencia de un campo de transportista obligatorio u otro fallo de validación específico del proveedor. No suponga que un número es no válido simplemente porque no se devuelven eventos de seguimiento.

Valide sin dañar el identificador

• Almacene los números de seguimiento como cadenas. El almacenamiento numérico puede eliminar ceros iniciales o alterar identificadores largos.
• Conserve la entrada original. Mantenga un valor normalizado independiente para que las transformaciones puedan auditarse.
• Normalice de forma conservadora. Elimine los espacios circundantes cuando corresponda, pero elimine caracteres internos o cambie el uso de mayúsculas y minúsculas solo cuando las reglas documentadas lo permitan.
• Compruebe localmente los campos obligatorios. Detecte números vacíos, identificadores de transportista ausentes y estructuras de solicitud no válidas antes de enviarlos.
• Evite una expresión regular universal para números de seguimiento. Una regla diseñada para un transportista puede rechazar identificadores válidos de otro.
• Confirme qué contiene el campo. Un número de pedido, una referencia de almacén y un número de seguimiento del transportista no son intercambiables, salvo que el endpoint los admita explícitamente.

Si la API rechaza explícitamente la entrada, diríjala a corrección en lugar de enviarla a un bucle de reintentos automático. Incluya un motivo útil, como “se requiere el identificador del transportista”, en vez de reducir todos los problemas de validación a “fallo de seguimiento”.

Trate “sin eventos” como un estado independiente

Un envío puede tener un identificador de seguimiento antes de que estén disponibles eventos de movimiento útiles. La respuesta correcta depende del modelo de estado documentado por la API y del contexto del envío. Compruebe si el identificador procede del sistema de envíos, si la selección del transportista es correcta y si la respuesta indica datos pendientes en lugar de una entrada rechazada.

Utilice estados internos diferenciados como input_rejected, awaiting_events y temporarily_unavailable. Estos son estados de aplicación sugeridos, no valores de API estandarizados. Ayudan a evitar que una brecha temporal de datos se convierta en un mensaje inexacto para el cliente.

Gestione los límites de frecuencia en toda la integración, no por trabajador

RFC 6585 define HTTP 429 como una respuesta de limitación de frecuencia y permite que incluya un encabezado Retry-After. El estándar no establece un límite ni un método de contabilización universal para las API de seguimiento. Los límites pueden estar documentados por cuenta, credencial, endpoint u otro ámbito; utilice las reglas reales del proveedor.

RFC 9110 especifica dos formas para Retry-After: un número no negativo de segundos o una fecha HTTP. Analice ambas. Si el valor es una fecha, calcule cuidadosamente la espera restante y tenga en cuenta las diferencias de reloj. Si falta o no se puede utilizar, aplique la política de retroceso alternativa configurada.

Que un trabajador se quede dormido de forma independiente no es suficiente cuando otros trabajadores siguen utilizando el mismo límite. Coloque el control de frecuencia en el límite compartido de la credencial o cuenta correspondiente. Un programador central, un depósito de tokens compartido o un control distribuido equivalente pueden coordinar ese tráfico.

1. Identifique el ámbito afectado. Determine a qué endpoint, credencial o cuenta se aplica el límite.
2. Respete la instrucción de espera del servidor. No programe un reintento anterior a lo que permita un valor válido de Retry-After.
3. Retrase el trabajo en cola afectado. Evite bloquear el tráfico no relacionado cuando los límites sean realmente independientes.
4. Reduzca la concurrencia o la frecuencia de solicitudes. Esperar una vez sin cambiar el patrón de solicitudes puede recrear el mismo problema.
5. Reanude con intervalos. No libere todo el retraso acumulado simultáneamente cuando termine la espera.

Cuando sea compatible, el procesamiento por lotes puede reducir el número de solicitudes, pero debe respetar las reglas documentadas sobre el tamaño de los lotes y la contabilización. No suponga que un lote consume una unidad del límite. Del mismo modo, utilice webhooks cuando estén disponibles para reducir el sondeo evitable, manteniendo el proceso de conciliación que requiera su integración.

Utilice reintentos acotados con retroceso y jitter

Los reintentos son apropiados cuando un fallo puede desaparecer sin cambiar la solicitud y repetir la operación es seguro. Los fallos temporales de conexión y ciertos errores del servidor pueden encajar en esa categoría. Un payload mal formado, una credencial no válida o un problema permanente de permisos generalmente requieren una corrección.

Una alternativa práctica es un retroceso exponencial limitado con jitter completo:

backoff_window = min(max_delay, base_delay * 2^retry_index)
jitter_delay = random(0, backoff_window)
next_delay = max(valid_retry_after_delay, jitter_delay)

Aquí, retry_index comienza en cero para el primer reintento, y la ausencia de Retry-After no añade ninguna espera mínima. Estas son decisiones de implementación, no un algoritmo HTTP obligatorio. Seleccione el retraso base, el límite, el número máximo de intentos y el plazo total según su carga de trabajo y las indicaciones del proveedor.

El jitter distribuye las solicitudes a lo largo del tiempo en lugar de hacer que todos los trabajadores las repitan según el mismo horario. El límite de retraso limita el componente exponencial; no debe anular una espera válida más larga solicitada por el servidor. Si dicha espera supera el plazo de su trabajo, aplace o termine el trabajo según la política, en lugar de reintentarlo antes de tiempo.

Dé un punto final a cada cadena de reintentos

• Límite de intentos: limite el número de solicitudes adicionales.
• Límite de tiempo transcurrido: deje de reintentar trabajos que hayan superado su ventana útil de procesamiento.
• Propiedad explícita: elija qué capa controla los reintentos para que los reintentos del cliente HTTP y de la cola no se multipliquen inesperadamente.
• Programación persistente: almacene los trabajos retrasados en lugar de depender de esperas prolongadas dentro de procesos de corta duración.
• Ruta de recuperación: envíe los trabajos agotados a una cola de trabajos fallidos revisable con un motivo y la siguiente acción.

Durante una interrupción prolongada, considere un disyuntor que pause temporalmente las llamadas rutinarias y permita sondas de recuperación controladas. Este es un patrón de resiliencia de aplicaciones, no una prueba de que un proveedor de seguimiento concreto lo requiera.

Resuelva las escrituras ambiguas antes de reenviarlas

Un tiempo de espera agotado indica que su aplicación no recibió una respuesta completa. No demuestra que el servidor rechazara o nunca procesara la solicitud. Esta distinción es importante al registrar números de seguimiento o cambiar la configuración de seguimiento.

RFC 9110 explica los métodos idempotentes y advierte contra el reintento automático de solicitudes no idempotentes sin una base para saber que la repetición es segura o que la operación original no se aplicó. Evalúe la semántica documentada de la operación en lugar de suponer que todos los endpoints de seguimiento se comportan como una consulta de solo lectura.

• Utilice un mecanismo de idempotencia documentado por el proveedor cuando esté disponible, siguiendo sus reglas de alcance y conservación.
• Mantenga la misma clave de idempotencia para los reintentos de la misma operación lógica; no suponga que se respetará un encabezado personalizado arbitrario.
• Si es compatible, compruebe el registro existente antes de repetir una escritura ambigua.
• Utilice una restricción de unicidad local alineada con la identidad del envío documentada por el proveedor.
• Almacene el resultado de la operación para que la redelivery de una cola no active automáticamente otra escritura.

Para las operaciones por lotes, persista el resultado de cada elemento. Reintente solo los elementos clasificados como fallos transitorios y concilie los elementos cuyo resultado siga siendo desconocido. Reproducir todo el lote puede repetir trabajo exitoso y consumir innecesariamente el límite de solicitudes.

Aplique la política a su proveedor de seguimiento

Para una integración con 17TRACK, utilice la página de la API de seguimiento y la documentación oficial de la API como puntos de partida para el contrato específico del proveedor. Mantenga configurable el clasificador de errores en lugar de codificar supuestos de una guía HTTP genérica.

Antes de la implementación, confirme el esquema de solicitud del endpoint correspondiente, el contenedor de respuesta, el significado de los errores a nivel de elemento, el ámbito del límite de frecuencia, las restricciones de los lotes y las reglas para envíos duplicados. Cuando utilice la entrega de eventos, verifique también los requisitos de confirmación, autenticación y redelivery. Esta guía no prescribe un límite de frecuencia, un calendario de reintentos ni una función de idempotencia numéricos para 17TRACK.

Registre cada regla confirmada en una asignación de la respuesta del proveedor a la acción de la aplicación: corregir la entrada, reparar la configuración, esperar, conciliar o escalar. Un error no reconocido debe conservar el contexto de diagnóstico y seguir una ruta alternativa acotada, no recurrir por defecto a reintentos ilimitados.

Supervise la calidad de recuperación y pruebe las rutas de fallo

Registre la operación, el endpoint, el estado HTTP, el código de error de la aplicación, el número de intento, la latencia, la siguiente acción programada y el identificador de solicitud del proveedor cuando se proporcione. Evite registrar claves de API, información de dirección innecesaria o cuerpos de respuesta sin restricciones. Enmascare o aplique un hash a los identificadores de seguimiento cuando no se necesiten sus valores completos.

Realice un seguimiento independiente de las tasas de entradas no válidas, la limitación de frecuencia, la antigüedad de la cola, los reintentos agotados y la última sincronización correcta. Una integración puede tener una baja tasa de errores HTTP y aun así ofrecer información de envíos obsoleta. Las páginas orientadas al cliente deben conservar el último estado conocido del envío y distinguir un fallo de actualización de una excepción de entrega comunicada por el transportista.

Antes del lanzamiento, pruebe entradas mal formadas, identificadores válidos sin eventos, ambas formas de Retry-After, encabezados ausentes, fallos parciales de lotes, tiempos de espera agotados después de escrituras y redelivery de colas. Simule también una interrupción lo bastante larga como para agotar el presupuesto de reintentos. La prueba solo se supera cuando el trabajo se detiene o se aplaza de forma predecible, los elementos exitosos no se reproducen innecesariamente y los elementos fallidos siguen siendo recuperables.

Preguntas frecuentes

¿Debe reintentarse automáticamente un número de seguimiento no válido?

No cuando la API rechaza explícitamente la entrada como no válida. Corrija primero el número, la selección del transportista o los campos obligatorios. Si la respuesta significa que los eventos del envío aún no están disponibles, utilice el flujo de actualización documentado en lugar de tratarlo como un fallo de validación.

¿HTTP 200 significa que una solicitud por lotes se completó correctamente?

No necesariamente. Compruebe el esquema de respuesta del proveedor para conocer los resultados a nivel de operación y de elemento. Persista los éxitos y aísle los fallos para que reintentar un elemento no repita innecesariamente los demás.

¿Cuántos intentos de reintento debe permitir una integración de seguimiento?

No existe una cantidad universal. Establezca un límite de intentos y un presupuesto de tiempo transcurrido según las indicaciones del proveedor, la seguridad de la operación y el tiempo durante el cual el resultado siga siendo útil. Una sincronización en segundo plano programada puede tolerar una ventana de recuperación diferente de la de una solicitud interactiva del cliente.

¿Debe un tiempo de espera agotado marcar inmediatamente un envío como fallido?

No. El tiempo de espera agotado de una solicitud es un resultado de la integración, no un evento del envío. Conserve el último estado de seguimiento conocido, programe una recuperación segura y evite convertir un problema de conectividad en una notificación de fallo de entrega.

¿Qué debe ocurrir cuando se agotan los reintentos?

Mueva el trabajo a una cola persistente de trabajos fallidos o de revisión con su contexto de diagnóstico. Identifique si la recuperación requiere una entrada corregida, credenciales restauradas, asistencia del proveedor o una reproducción controlada posterior. No lo descarte silenciosamente ni reinicie el mismo ciclo de reintentos ilimitados.

Fuentes

• RFC 9110: Semántica HTTP — semántica de los estados HTTP, métodos idempotentes, consideraciones sobre reintentos automáticos y el campo Retry-After.
• RFC 6585: Códigos de estado HTTP adicionales — definición de 429 Too Many Requests y su encabezado Retry-After opcional.
• API de seguimiento de 17TRACK — punto de entrada oficial del producto de API de seguimiento.
• Documentación de la API de 17TRACK — referencia para comprobar los requisitos específicos de integración del proveedor.