Menú de la documentación

Inicio

Fundamentos de proxy

API de proxies

Caché de respuestas

API de Litport

Servidor MCP

Referencia de errores de proxy

Los errores de proxy son fallos del plano de datos en la entrada HTTP o SOCKS5. Son independientes de los errores JSON que devuelve Litport API.

Errores del proxy HTTP#

En la entrada HTTP, revisa estos encabezados de respuesta antes de interpretar el estado HTTP:

X-Proxy-Error-Code: 10
X-Proxy-Error-Message: Too many requests

El encabezado numérico es el discriminador principal. El estado HTTP por sí solo no basta: varias rutas de compatibilidad usan 500, mientras que algunos fallos de red se deducen como 503. Los códigos 11 y 12 pueden llevar un mensaje más específico en la conexión que el predeterminado de más abajo.

El código 13 (saldo insuficiente en la cuenta) es la excepción a la convención del 500: devuelve 402 Payment Required. Muchos clientes informan solo la línea de estado cuando falla un túnel HTTPS, así que el estado por sí solo les indica que el problema es el saldo. Recarga tu saldo antes de reintentar.

Código Símbolo Mensaje predeterminado o enviado Estado(s) HTTP Guía de reintento Qué hacer
0 ErrorNone Vacío Sin respuesta de error No aplicable Considera la solicitud como exitosa.
1 ErrorPanic panic 500 No reintentar en bucle sin pausa Reintenta una vez con backoff y luego ponte en contacto con soporte e incluye la evidencia de la solicitud.
2 ErrorInternal Internal proxy error 500 o 503 Backoff acotado Reintenta un número limitado de veces y luego ponte en contacto con soporte.
3 ErrorInterrupted Connection was interrupted 500 Solo cuando la operación de la aplicación sea segura Revisa los tiempos de espera del cliente y del destino antes de reintentar.
4 ErrorNoToken Token not found 407 Después de corregir las credenciales Revisa el usuario, la contraseña, el host y el puerto del proxy.
5 ErrorNoAccess Access denied 500 por compatibilidad Sin reintento automático Revisa el estado del token, el acceso de la cuenta y la política de destino.
6 ErrorLimited You have reached the limit of concurrent connections 403 Cuando haya capacidad disponible Cierra las conexiones inactivas o reduce la concurrencia.
7 ErrorNoProxy Internal proxy error 500 Backoff acotado Reintenta en unos momentos; ponte en contacto con soporte si no hay ningún upstream disponible.
8 ErrorHubMismatch Proxy host mismatch, check token settings 500 Después de corregir el hub Usa el hub que se muestra para el token en el panel.
9 ErrorHubProxyTypeMismatch Proxy type mismatch, check token settings 500 Después de corregir la entrada Usa el endpoint HTTP o SOCKS5 actual del token.
10 ErrorRateLimited Too many requests 403 Backoff obligatorio Reduce la frecuencia de solicitudes nuevas o de conexiones nuevas para el modo de entrada.
11 ErrorPpgGetProxy PPG proxy error Puede reemplazarse por un mensaje específico enviado. 500 Depende del mensaje personalizado Corrige los parámetros de pool, geografía o sesión; si no, reintenta con backoff.
12 ErrorPpgStats PPG stats error El mensaje enviado puede ser personalizado. 500 Backoff acotado Reintenta en unos momentos y, si el error continúa, ponte en contacto con soporte.
13 ErrorPpgNotEnoughUnits Insufficient account balance 402 No es un reintento de red Revisa el saldo de la cuenta o recárgalo en el panel.
14 ErrorRemoteProxy Remote proxy connection error 500 o 503 Backoff acotado Reintenta con backoff; un reintento puede seleccionar otro proxy remoto. Si segmentas por país, región o ciudad y el error persiste, puede que esa ubicación no tenga ninguna IP en línea en este momento: reintenta más tarde o amplía la ubicación.
15 ErrorUpstreamConnection Upstream server connection error 500 o 503 Depende de la seguridad del destino Revisa el destino y la política de reintentos antes de reintentar.
16 ErrorPpgUpstreamResponse Internal proxy error 500 Backoff acotado Reintenta en unos momentos; si persiste, ponte en contacto con soporte e indica el hub, el ID del token, el destino, la marca de tiempo y el código 16—nunca la contraseña del proxy.
17 ErrorPackageBandwidthExceeded packageBandwidthExceeded 403 No es un reintento de red Solo un paquete más antiguo con límite de tráfico puede llegar a este error: ya usó su tráfico del período actual. Espera a que el período se renueve o ponte en contacto con soporte.
18 ErrorPackageEntitlementUnavailable packageEntitlementUnavailable 503 Backoff acotado No se pudieron leer o reservar a tiempo los derechos de uso del paquete. Reintenta en unos momentos; si persiste, ponte en contacto con soporte e indica el hub, el ID del token y la marca de tiempo.
19 ErrorPackageInactive packageInactive 403 Sin reintento automático El paquete está suspendido o cancelado. Revisa su estado y su método de pago en el panel.
20 ErrorPackageExpired packageExpired 403 Sin reintento automático El período del paquete ha terminado. Renuévalo o compra un paquete nuevo en el panel.
21 ErrorPackageMissing packageMissing 403 Sin reintento automático El token hace referencia a un paquete que ya no existe. Ponte en contacto con soporte e indica el ID del token.
22 ErrorPackageStale packageEntitlementStale 403 Sin reintento automático El hub conserva un registro del paquete demasiado antiguo para ser fiable. Ponte en contacto con soporte e indica el hub, el ID del token y la marca de tiempo.
23 ErrorClientAborted Client closed the connection No se envía (el cliente ya había cerrado) No aplicable Tu cliente cerró o restableció la conexión antes de que terminara la solicitud. Revisa los tiempos de espera del cliente y la reutilización de conexiones.

Para un token móvil compartido «Multiubicación», el código 7 con el mensaje noHealthyRoute significa que el destino guardado no tiene ahora ningún dispositivo operativo. Lee la ubicación del token y luego espera a que se recupere o elige otro destino disponible. La ciudad siempre se mantiene: un operador sin ningún teléfono en funcionamiento en esa ciudad pasa a otro operador de la misma ciudad, y effective muestra el operador que se usa realmente.

Un handshake TLS fallido con el endpoint de proxy HTTP en https:// se manifiesta como una conexión cerrada antes de enviarse cualquier respuesta HTTP, así que no hay un X-Proxy-Error-Code que revisar. Si una conexión https:// se cierra de inmediato, comprueba el esquema de la URL, el nombre de host (no una dirección IP) y que el cliente confíe en la raíz de caché de Litport para la conexión con el proxy.

Fallos upstream de PPG#

El código 16 significa que un upstream de pago por GB no pudo atender la solicitud. No significa que el destino haya devuelto el 500 de Litport. El código 14 significa que el proxy remoto rechazó o cortó la conexión, por ejemplo porque no hay ninguna IP en línea en la ubicación elegida. En ambos casos Litport reemplaza a propósito el estado, los encabezados y el cuerpo del proveedor upstream por su propio error fijo.

Los clientes HTTP deben ramificar su lógica según X-Proxy-Error-Code: 16, y no solo según el estado HTTP. Los clientes SOCKS5 reciben un fallo general sin el encabezado numérico; para ver el código de Litport, reproduce solo una solicitud segura e idempotente a través de la entrada HTTP del token.

Reintenta con backoff acotado. Si el error persiste, ponte en contacto con soporte e indica el hub, el ID del token, el destino, la marca de tiempo y el código 16—nunca la contraseña del proxy. El tráfico intercambiado después de la admisión, incluida la respuesta de error genérica, sigue sujeto a la política de uso vigente.

Respuestas SOCKS5#

SOCKS5 no expone X-Proxy-Error-Code ni X-Proxy-Error-Message. Varias categorías internas se agrupan a propósito en una sola respuesta.

La mayoría de las comprobaciones del token y de la cuenta, incluido el saldo insuficiente, se ejecutan durante el inicio de sesión con usuario y contraseña, antes de que el cliente envíe una solicitud. Un fallo en ese punto cierra la conexión como un inicio de sesión rechazado, que la mayoría de los clientes informan como un fallo de autenticación aunque la contraseña sea correcta.

Respuesta Significado Categorías posibles
auth 0x01 Inicio de sesión rechazado Falló el paso de usuario y contraseña (RFC 1929) y la conexión se cerró antes de cualquier solicitud. Aquí se ejecutan la mayoría de las comprobaciones de token y de cuenta: token desconocido, desactivado o caducado, o contraseña incorrecta (4), discrepancia en el acceso del token (5), hub (8) o protocolo (9) incorrecto, parámetros de pool PPG no válidos (11), contabilidad de PPG (12), saldo insuficiente (13) y estado del paquete (17–22). Los clientes suelen informar de esto como un error de autenticación.
0x01 Fallo general Fallo interno, o la conexión upstream falló después de que se admitió la solicitud. Códigos habituales: 2, 14, 15 o 16.
0x02 Conexión no permitida La solicitud se rechazó después del inicio de sesión: reglas de destino o de red (5), límite de conexiones simultáneas (6), ningún upstream disponible (7), límite de frecuencia (10), selección de upstream PPG (11) o UDP de PPG que el upstream seleccionado no admite.
0x07 Comando no admitido El comando SOCKS5 solicitado no está implementado; esto no es un X-Proxy-Error-Code.

Para distinguir la causa, reproduce la misma solicitud segura e idempotente y las mismas credenciales en la entrada HTTP correspondiente y revisa sus encabezados. Si reproducirla repetiría un efecto secundario o no fuera segura por otro motivo, no la reproduzcas.

Política de reintentos seguros#

  1. Corrige las credenciales, el hub, el protocolo, la geografía, el saldo o la concurrencia del cliente antes de reintentar fallos deterministas.
  2. Reintenta los fallos transitorios internos, de selección y de upstream con backoff exponencial acotado y jitter.
  3. Reintenta una operación de la aplicación que se interrumpió o que falló en el upstream solo cuando repetir esa operación sea seguro.
  4. Nunca ejecutes un bucle de reintentos sin pausa. Conserva la primera y la última evidencia de una secuencia acotada.

Evidencia para soporte#

Incluye el hub de Litport, la entrada HTTP o SOCKS5, la marca de tiempo en UTC, el ID del token, el host y el puerto de destino, y el código y mensaje de error observados o la respuesta SOCKS5. Incluye el método de la solicitud cuando sea relevante.

MarkdownOpenAPI