Errores de la API

Todos los endpoints bajo https://litport.net/api/v1 (Tokens, Paquetes y Pago por GB) devuelven sus errores en el formato JSON descrito en esta página. Los fallos de la propia conexión a través del proxy usan códigos de error de proxy numéricos y aparte, y la API pública de proxies gratis no se trata aquí.

Envoltorio del error#

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication failed.",
    "requestId": "req_example",
    "docsUrl": "https://litport.net/docs/api/errors"
  }
}

El mismo ID de solicitud aparece en el encabezado X-Request-ID. Regístralo junto con el estado HTTP y el código de error. No registres nunca el encabezado Authorization.

Un 409 que indica un tiempo de espera agrega además nextChangeAt, una marca de tiempo ISO-8601 en UTC: es el caso de CHANGE_LIMIT al cambiar la ubicación de un token o al obtener una IP nueva.

Referencia de estados#

Algoritmo de reintentos#

Reintenta automáticamente los 429 y 503 respetando Retry-After y agregando jitter, salvo un 503 en POST /tokens/{tokenId}/new-ip (ver más abajo). Limita el número de intentos y haz visible para quien llama el presupuesto total de reintentos.

Cualquier escritura de esta API se puede repetir sin riesgo, excepto new-ip: un 409 CONCURRENT_CHANGE o una respuesta ambigua (tiempo de espera agotado, respuesta perdida, 503) se puede volver a enviar sin más, porque la última escritura siempre prevalece y cualquier otra escritura no hace nada si ya está aplicada. Con new-ip, un resultado ambiguo implica leer primero GET /tokens/{tokenId}/location y reintentar solo cuando nextChangeAt no sea posterior a la hora actual. Repetir a ciegas dentro de la semana solo devuelve 409 CHANGE_LIMIT.

Detalle de los códigos de error#

Cuerpo de solicitud no válido#

400 cuando el cuerpo no se puede interpretar como JSON o no pasa la validación de estructura propia del endpoint (por ejemplo, PUT /tokens/{tokenId}/rotation requiere exactamente {"intervalSec": <integer>}). 413 cuando el cuerpo supera 4 KiB.

Tipo de contenido no válido#

INVALID_CONTENT_TYPE significa que se envió una escritura con cuerpo sin Content-Type: application/json.

Límite no válido#

INVALID_LIMIT significa que limit no es un número entero del 1 al 100.

Cursor no válido#

INVALID_CURSOR significa que el cursor opaco tiene un formato incorrecto, fue modificado, no se puede autenticar o se emitió para otro endpoint. Reinicia la paginación sin cursor.

Tipo no válido#

INVALID_TYPE significa que type en GET /tokens no es unlimited ni ppg.

Estado no válido#

INVALID_STATUS significa que status en GET /tokens no es active, expired ni disabled.

ID de paquete no válido#

INVALID_PACKAGE_ID significa que el filtro packageId de GET /tokens no es un entero positivo. Un packageId en la ruta de una URL nunca da 400: uno desconocido o ajeno da 404 PACKAGE_NOT_FOUND.

Rango de tiempo no válido#

INVALID_TIME_RANGE significa que una marca de tiempo no está en UTC canónico, que from no es anterior a to o que el intervalo solicitado es demasiado grande.

Agrupación no válida#

INVALID_GROUP_BY significa que groupBy no es hour, day ni month.

Expansión no válida#

INVALID_INCLUDE significa que la expansión solicitada es incompatible con el token o la agrupación; los componentes de cobro requieren un token PPG y intervalos por hora.

Pool no válido#

INVALID_POOL significa que pool en GET /pay-per-gb/geo falta, está vacío o contiene una clave de autenticación que no corresponde a un pool que el cliente pueda elegir.

Nivel no válido#

INVALID_LEVEL significa que level no es uno de los valores que acepta ese endpoint: region/city para las opciones de ubicación de un token, o country/region/city para la segmentación geográfica de pago por GB.

Elemento superior no válido#

INVALID_PARENT significa que falta una geografía superior obligatoria: location/options?level=city de un token necesita region; GET /pay-per-gb/geo necesita country tanto con level=region como con level=city.

Segmentación geográfica no habilitada#

GEO_NOT_ENABLED significa que un pool solicitado tiene desactivada la segmentación geográfica.

Nivel geográfico no compatible#

GEO_LEVEL_UNSUPPORTED significa que un pool solicitado no admite el level solicitado. Consulta los geoLevels del pool en Pago por GB.

IP no válida#

INVALID_IP significa que la dirección enviada no es un literal IPv4 público exacto.

IPv6 no compatible#

IPV6_UNSUPPORTED significa que se envió una dirección IPv6 a una escritura de IP permitidas de un paquete; ponte en contacto con soporte.

Ubicación no válida#

INVALID_LOCATION significa que la región, la ciudad o el operador solicitados no son un valor que este token pueda usar, o que country se envió con un valor distinto de "us".

Rotación no válida#

INVALID_ROTATION significa que intervalSec en PUT /tokens/{tokenId}/rotation no es una de las options indicadas para el token.

No autorizado#

UNAUTHORIZED cubre las claves ausentes, mal formadas, desconocidas, rotadas y sin propietario, sin revelar cuál de esos casos ocurrió.

Token no encontrado#

TOKEN_NOT_FOUND cubre un tokenId ausente, ajeno o que no se puede interpretar en cualquier ruta de tokens. La respuesta es idéntica en todos los casos, por lo que nunca revela el token de otro usuario.

Paquete no encontrado#

PACKAGE_NOT_FOUND cubre un packageId ausente, ajeno o que no se puede interpretar en cualquier ruta de paquetes, incluidas las IP permitidas de un paquete.

No encontrado#

NOT_FOUND significa que la ruta /api/v1 solicitada no existe.

Método no permitido#

METHOD_NOT_ALLOWED significa que un endpoint conocido recibió un método no admitido. La respuesta incluye los métodos admitidos en Allow.

No compatible#

NOT_SUPPORTED significa que este token no tiene ese control: no se puede cambiar su ubicación, no se puede cambiar su intervalo de rotación o (new-ip) no es un proxy estático de centro de datos o ISP. El intervalo de rotación de un token «Multiubicación» siempre responde NOT_SUPPORTED, porque lo define el teléfono en el que está el proxy.

Paquete inactivo#

PACKAGE_INACTIVE significa que el periodo pagado del token o del paquete no está activo en este momento.

Cambio simultáneo#

CONCURRENT_CHANGE significa que otra escritura en el mismo token o paquete se aplicó en el mismo instante. Reintenta la misma solicitud.

Ubicación no disponible#

LOCATION_UNAVAILABLE significa que la ubicación solicitada no tiene ahora ninguna IP utilizable ni dispositivo en funcionamiento. No se cambió nada.

Límite de cambios#

CHANGE_LIMIT significa que ya se usó el cupo de cambios o reemplazos: una vez por semana para una IP nueva o un cambio de ubicación de un proxy estático de centro de datos o ISP, una vez cada 48 horas para un cambio de ubicación de un proxy móvil compartido estándar de Estados Unidos. El error incluye nextChangeAt y un Retry-After equivalente.

Límite de IP permitidas alcanzado#

ALLOWED_IPS_LIMIT_REACHED significa que la lista de IP permitidas del paquete ya alcanzó su limit (1 o 50). Ponte en contacto con soporte para aumentarlo.

Límite de frecuencia superado#

RATE_LIMITED significa que la clave de API, o el paquete en el caso de una escritura de IP permitidas, agotó su ventana actual. Respeta Retry-After.

Servicio no disponible#

SERVICE_UNAVAILABLE significa que una dependencia de la API no está disponible temporalmente. Respeta Retry-After.

Datos del token no válidos#

TOKEN_DATA_INVALID significa que los metadatos almacenados de un token no se pueden leer temporalmente. Reintenta más tarde y después informa el ID de solicitud.

IP permitidas no disponibles#

ALLOWED_IPS_UNAVAILABLE significa que el almacenamiento, la configuración o la asignación de puertos de las IP permitidas no está disponible, incluido el caso de un paquete que se quedó temporalmente sin puertos asignables.

Fallos de autenticación#

La API devuelve a propósito el mismo envoltorio 401 para claves mal formadas, desconocidas, rotadas y sin propietario. Crea o rota una clave de API en Configuración. Una rotación invalida de inmediato la clave activa anterior.