Errores de la API

Todos los endpoints bajo https://litport.net/api/v1 (Tokens y uso, 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",
    "retryable": false
  }
}

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.

retryable siempre está presente, con valor true o false. true significa que la misma solicitud, enviada de nuevo sin cambios después de Retry-After (o de nextChangeAt, si el error lo incluye), puede tener éxito y se puede enviar otra vez sin riesgo: no se hizo nada (RATE_LIMITED, CONCURRENT_CHANGE, CHANGE_LIMIT, ALLOWANCE_CONFLICT), o es un 503 en una solicitud que se puede repetir sin riesgo. false significa que primero debes cambiar algo: la solicitud, la cuenta o el token. Un 503 en una solicitud que no se puede repetir sin riesgo también es false: lee el estado actual antes de decidir (consulta el Algoritmo de reintentos).

Referencia de estados#

Algoritmo de reintentos#

Reintenta automáticamente solo cuando retryable sea true: espera Retry-After (y hasta nextChangeAt, si el error lo incluye), agrega jitter y vuelve a enviar la misma solicitud. Limita el número de intentos y haz visible para quien llama el presupuesto total de reintentos. Cuando retryable sea false, cambia primero algo o, tras un fallo poco claro de una solicitud que no se puede repetir sin riesgo (ver más abajo), lee el estado actual antes de decidir.

Cualquier escritura de esta API se puede repetir sin riesgo, excepto new-ip, POST /tokens sin un externalRef, POST /tokens/{tokenId}/credentials sin un requestId, PUT /tokens/{tokenId}/location con {"random": true} y los dos POST de la API de soporte (POST /support/conversations y POST /support/conversations/{conversationId}/messages). Cualquier otra escritura que reciba 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. Un 503 en una solicitud que no se puede repetir sin riesgo lleva retryable: false, porque el trabajo pudo haberse hecho antes del fallo.

Con new-ip en un token estático, 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.

Una creación se puede repetir sin riesgo cuando lleva un externalRef: la repetición devuelve el proxy que ya existe. Sin él, una repetición puede crear un segundo proxy. Una reemisión se puede repetir sin riesgo cuando lleva un requestId: la repetición devuelve las credenciales que emitió la primera llamada. Sin él, una repetición emite otro par. Consulta Crear y administrar proxies.

En un token rotativo, new-ip no se puede confirmar con GET /tokens/{tokenId}/location: su canChangeNow y su nextChangeAt hablan de la ubicación y no dicen nada sobre la espera entre IP nuevas. Enviarlo de nuevo después de Retry-After no hace daño; solo da otra IP nueva. Un 409 CHANGE_LIMIT justo después de una respuesta perdida no demuestra que el cambio se hiciera, porque una respuesta 409 LOCATION_UNAVAILABLE también consume la espera.

PUT /tokens/{tokenId}/location con {"random": true} elige una ubicación nueva cada vez, así que una repetición vuelve a mover el proxy siempre que no haya ninguna espera. Tras una respuesta perdida, lee primero GET /tokens/{tokenId}/location y vuelve a enviarla solo si el proxy no está donde quieres. Los dos POST de la API de soporte no tienen clave de idempotencia, y un 503 puede llegar después de que se haya guardado el mensaje: lee la conversación antes de enviar el mensaje de nuevo.

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>}). En POST /tokens, PATCH /tokens/{tokenId} y POST /tokens/{tokenId}/credentials el cuerpo debe ser un objeto JSON que contenga solo los campos que admite esa llamada, y un PATCH necesita al menos uno. 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 token no válidos#

INVALID_TOKEN_IDS significa que tokenIds en GET /usage no es una lista de IDs de proxy positivos, o nombra más de 100.

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, POST /tokens o PATCH /tokens/{tokenId} falta donde es obligatorio, 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.

Etiqueta no válida#

INVALID_LABEL significa que label no es un texto de 255 caracteres como máximo, ni null para borrarla.

Referencia externa no válida#

INVALID_EXTERNAL_REF significa que externalRef no tiene entre 1 y 128 caracteres imprimibles.

ID de solicitud no válido#

INVALID_REQUEST_ID significa que requestId en POST /tokens/{tokenId}/credentials no tiene entre 1 y 64 caracteres, entre letras, dígitos, guion bajo o guion.

Activación no válida#

INVALID_ENABLED significa que enabled no es true ni false.

Caducidad no válida#

INVALID_EXPIRY significa que expiresAt no es una fecha y hora ISO 8601 con zona horaria, ni una fecha, que además todavía esté por llegar, ni null.

Tope de tráfico no válido#

INVALID_ALLOWANCE significa que allowanceBytes no es un entero de al menos 1 (bytes), ni null para quitar el tope.

Campo no permitido#

FIELD_NOT_ALLOWED significa que PATCH /tokens/{tokenId} envió a un proxy de un paquete un campo distinto de label. Los proxies de un paquete los activa y desactiva su paquete.

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 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. DELETE /tokens/{tokenId} en un proxy de un paquete también la devuelve: solo se pueden eliminar los proxies de pago por GB.

Saldo insuficiente#

INSUFFICIENT_BALANCE es 402. Crear un proxy y activarlo necesitan un saldo positivo. Todo lo demás funciona con el saldo vacío: desactivar, cambiar la etiqueta, cambiar la caducidad o el tope, volver a emitir las credenciales y eliminar.

Cuenta bloqueada#

ACCOUNT_BANNED es 403. Una cuenta bloqueada no puede crear un proxy ni activarlo. Desactivar, volver a emitir las credenciales y eliminar siguen funcionando. Ponte en contacto con soporte.

Límite de tokens alcanzado#

TOKEN_LIMIT_REACHED significa que la cuenta ya tiene el máximo de proxies de pago por GB que puede tener. Elimina uno que ya no uses o ponte en contacto con soporte para aumentar el límite.

Token no editable#

TOKEN_NOT_EDITABLE significa que el proxy ya no se puede editar, por ejemplo porque se eliminó mientras se ejecutaba la escritura. No cambió nada. Lee el proxy para ver en qué estado está.

Conflicto con el tope de tráfico#

ALLOWANCE_CONFLICT significa que no se pudo guardar el tope de tráfico. No cambió nada. Envía de nuevo la misma solicitud.

Se requiere un pool para la autenticación por IP#

POOL_REQUIRED_FOR_IP_AUTH significa que se envió pool: null para un proxy que inicia sesión por IP permitida. Ese proxy conserva un pool.

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.

No está en estado fallback#

NOT_IN_FALLBACK es la respuesta de POST /tokens/{tokenId}/location/return cuando el token no está fuera de su ubicación guardada, así que no hay nada que mover de vuelta. Una repetición de una solicitud que ya funcionó llega aquí y no da una segunda IP. No 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. Para una IP nueva en un token rotativo de centro de datos/ISP, la espera es el valor más corto de rotation.options del token, contada desde la última solicitud. 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 (para GET /usage, su propio límite de 10 solicitudes cada 60 segundos), en una escritura de IP permitidas el paquete, o en POST /tokens la cuenta (su límite de creación de proxies nuevos por minuto, compartido por todas sus claves y el panel), agotó su ventana actual. No se hizo nada. Respeta Retry-After; retryable es true.

Servicio no disponible#

SERVICE_UNAVAILABLE significa que una dependencia de la API no está disponible temporalmente. Respeta Retry-After. retryable es false cuando la solicitud no se puede repetir sin riesgo; consulta el Algoritmo de reintentos.

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.