# Códigos de error

Esta página enumera los códigos de error habituales que devuelve la API de MoreLogin.

## Formato de respuesta

Todas las respuestas de la API siguen este formato estándar:

```json
{
  "code": 0,
  "msg": null,
  "data": {},
  "requestId": "unique-request-id"
}
```

| Campo | Tipo | Descripción |
|  --- | --- | --- |
| `code` | integer | `0` = correcto, `>0` = error |
| `msg` | string | Mensaje de error (null cuando es correcto) |
| `data` | object | Datos de la respuesta |
| `requestId` | string | Identificador único de la petición para diagnóstico |


## Cómo identifica un código su área

Los códigos no se asignan desde una lista plana. Cada área de producto tiene su propio rango, así que los dos o tres primeros dígitos indican qué subsistema rechazó la petición:

| Rango | Área |
|  --- | --- |
| `14xxx` | Proxies |
| `15xxx` | Grupos y etiquetas |
| `19xxx` | Perfiles de navegador |
| `20xxx` | Monedero, pedidos y facturación |
| `21001` | Versión del cliente demasiado antigua |
| `33xxx` | Cloud Phone |
| `35xxx` | Autenticación de API y límites de frecuencia |
| `39xxx` | Cloud Storage |
| `40xxx` | Runtimes de Cloud Browser |
| `41xxx` | Configuración de webhooks |
| `99xxx` | Puerta de enlace y validación de peticiones |


Cada operación enumera los códigos que se sabe que devuelve. Consulta las matrices por producto enlazadas desde la [matriz de reintentos y finalización de endpoints](/es/api-reference/getting-started/endpoint-behavior).

## Códigos de error comunes

Los devuelve cualquier operación, porque provienen de la validación de la petición, las comprobaciones de permisos y la puerta de enlace, no de la lógica de negocio.

| Código | Descripción | Solución |
|  --- | --- | --- |
| `0` | Correcto | — |
| `21001` | Versión del cliente demasiado antigua | Actualiza el cliente de escritorio de MoreLogin |
| `35000` | Peticiones a la API demasiado frecuentes | Reintenta las operaciones aptas con retroceso y jitter; consulta [Límites de frecuencia](/es/api-reference/getting-started/rate-limits) |
| `99000` | Error de sistema desconocido | Reintenta más tarde e indica el `requestId` a soporte |
| `99001` | Parámetros de la petición no válidos | Revisa el formato del cuerpo y los campos obligatorios |
| `99002` | Permiso denegado | Revisa los permisos de tu cuenta |
| `99003` | Excepción en la petición | Haz el ajuste de negocio necesario según `msg` |
| `99004` | Cuerpo de la petición demasiado grande | Reduce el cuerpo de la petición |
| `99005` | Ya hay una petición igual en curso | Espera a que termine la petición en vuelo antes de reintentar |
| `99006` | Petición incorrecta | Revisa el método HTTP, las cabeceras y el cuerpo |
| `99007` | La IP de la petición no está en la lista de permitidos | Añade la IP que llama a la lista de permitidos |
| `99008` | Cuota de peticiones por IP o dispositivo superada | Reduce el volumen de peticiones desde esta IP o dispositivo |
| `99009` | Demasiadas peticiones | Retrocede con jitter y reintenta |
| `99011` | La marca de tiempo de la petición ha caducado | Reenvía con una marca de tiempo actual |
| `99012` | Se requiere permiso de costes | Usa la cuenta del propietario del equipo, o concede el permiso de costes |


### Cloud Phone (`33xxx`)

| Código | Descripción | Solución |
|  --- | --- | --- |
| `20002` | The original monthly order was cancelled | Create a new monthly purchase for eligible Cloud Phones |
| `20003` | The original monthly order was refunded | Create a new monthly purchase for eligible Cloud Phones |
| `20004` | The original monthly order does not exist | Verify the Cloud Phone purchase state and contact support with `requestId` if it persists |
| `20008` | The original monthly order is not completed or its status cannot be confirmed | Check the order and Cloud Phone state before retrying |
| `20055` | A Cloud Phone does not exist, was deleted, or does not belong to the team | Verify every Cloud Phone ID and team ownership |
| `20068` | A pending monthly payment order already exists | Complete or cancel the pending order before using the activation API |
| `20070` | A concurrent Cloud Phone purchase is already in progress | Wait for the in-flight purchase to settle, then read state before retrying |
| `20071` | A selected monthly SKU is unavailable or has no active 30-day price | Query the monthly SKU endpoint again and choose an available product |
| `33420` | Paid and unpaid Cloud Phones cannot be activated in the same batch | Separate Cloud Phones by purchase state and submit compatible batches |
| `33421` | Paid Cloud Phones from different purchase orders cannot be mixed | Submit one activation batch per original purchase order |
| `33422` | Payment succeeded but activation is incomplete or cannot yet be confirmed | Inspect `data.results` and each Cloud Phone's expiry state; do not pay again blindly |
| `33300` | El Cloud Phone no existe | Verifica el ID del Cloud Phone y que pertenece a tu equipo |
| `33301` | El Cloud Phone no está encendido | Enciéndelo y espera a que llegue a un estado ejecutable |
| `33308` | Otro miembro lo está usando, no se puede apagar | Reintenta cuando el otro miembro lo libere |
| `33309` | Otro miembro lo está usando, no se puede conectar | Reintenta cuando el otro miembro lo libere |
| `33315` | Cuenta con deuda, Cloud Phone congelado | Recarga el monedero |
| `33316` | No hay suficientes perfiles disponibles | Mejora el plan |
| `33317` | Se revocó el permiso del perfil | Pide a un administrador que te dé acceso |
| `33318` | Saldo insuficiente para encender | Recarga el monedero |
| `33321` | El perfil no está disponible | Comprueba el estado del perfil antes de reintentar |
| `33322` | Comprobación del proxy en curso | Consulta hasta que termine la comprobación |
| `33323` | El perfil se está iniciando | Espera a que termine el inicio; no reenvíes |
| `33324` | El perfil ya está en ejecución | No hay nada que hacer |
| `33325` | El perfil está desactivado | Reactívalo antes de usarlo |
| `33331` | Nuevo dispositivo en un clic en curso, no se puede apagar | Espera a que termine |
| `33332` | Reinicio en curso, no se puede apagar | Espera a que termine |
| `33333` | Restablecimiento en curso, no se puede apagar | Espera a que termine |
| `33338`–`33345` | Falta o no es válido el país, la zona horaria, el idioma, la longitud o la latitud | Consulta la [tabla de países y zonas horarias](/es/api-reference/appendix/country-time-zone) |
| `33346` | El SKU ya no está a la venta | Elige otro `skuId` |
| `33347` | El modelo requiere la última versión del cliente de Windows | Actualiza el cliente de escritorio de MoreLogin |
| `33367` | En mantenimiento, no se puede encender | Consulta los avisos del sistema para la ventana de recuperación |
| `33376` | La facturación mensual ha caducado | Renueva la suscripción |
| `33398`–`33400` | Longitud, latitud o altitud fuera de rango | Longitud −180…180, latitud −90…90, altitud −50000…100000 |
| `33401` | El Cloud Phone no admite esta operación | Usa un modelo compatible |
| `33407` | Cuota del paquete de concurrencia superada | Espera una plaza o amplía la cuota |
| `33408` | El formato del número de teléfono no es válido | Empieza por `+`, código de país de 1–3 dígitos sin incluir 86, y 8–14 dígitos en total |
| `33418` | El archivo de transmisión no existe o no es válido | Súbelo con `uploadType=2` y usa el `fileId` devuelto |
| `33419` | El formato del archivo de transmisión no está admitido | Sube un MP4 a través de `/cloudphone/uploadFile` |
| `33005` | Falló la instalación de la app | Reintenta y comprueba el espacio de almacenamiento del dispositivo |
| `33014` | Operación demasiado frecuente | Retrocede y reintenta |
| `33714` | La app no existe o se ha retirado | Actualiza la biblioteca de apps |
| `33814` | La plantilla de RPA no existe | Vuelve a listar las plantillas y usa un `templateId` actual |
| `33818` | El formato del parámetro de la plantilla de RPA no es válido | Envía `templateParameter` como una cadena JSON escapada |
| `33303` | Falló la creación del Cloud Phone | Consulta `/cloudphone/page` antes de reintentar; no reenvíes a ciegas |
| `33320` | El proxy vinculado a este Cloud Phone fue eliminado | Vuelve a vincular un proxy con `/cloudphone/setProxy` |
| `33326` | Otro miembro lo está usando, no se puede reemplazar el dispositivo | Reintenta cuando el otro miembro lo libere |
| `33350` | No se pudo activar ADB en algunos Cloud Phones | Esos teléfonos no están en ejecución o no admiten ADB; vuelve a leer el estado y reintenta solo esos |
| `33507` | El archivo no existe en el dispositivo | Comprueba la ruta; la petición de descarga recorre el directorio padre antes de transferir |


Las operaciones de instalación y de encendido pueden devolver además un código asignado por el servicio de los rangos `33001`–`33033`, `33500`–`33520`, `33700`–`33724` o `33900`–`33910`. Cuál de ellos es alcanzable depende del servicio que atienda al dispositivo, así que las operaciones no los enumeran individualmente.

### Perfiles de navegador (`19xxx`)

| Código | Descripción | Solución |
|  --- | --- | --- |
| `19001` | El nombre del perfil ya existe | Elige un nombre único, u omite `envName` para que se genere uno |
| `19002` | Falló la creación del perfil aguas abajo | Confírmalo con `/env/page` antes de reintentar |
| `19004` | El formato del user agent no es válido | Envía un `advancedSetting.ua` que se pueda analizar |
| `19005` | El formato de las cookies no es válido | Envía `cookies` como una cadena JSON de array escapada |
| `19039` | Perfil no encontrado | Verifica `envId` / `uniqueId` y que pertenece a tu equipo |
| `19063` | Se alcanzó el límite de perfiles | Elimina perfiles o mejora el plan |
| `19064` | Sin permiso para este grupo | Pide a un administrador acceso al grupo |
| `19065` | Sin permiso para este perfil | Pide a un administrador acceso al perfil |
| `19099` | No hay suficientes perfiles disponibles, el uso está restringido | Mejora el plan |
| `19100` | El ID de plataforma no es válido | Usa un `platformId` devuelto por `/system/platform/list` |
| `19101` | El ID de sitio no es válido | Usa un `siteId` devuelto por `/system/platform/list` |
| `19102` | La URL de plataforma personalizada no puede estar vacía | Envía `platformUrl` cuando `platformId` sea `9999` |
| `19103` | El formato de la URL de apertura automática no es válido | Envía URL absolutas válidas en `afterStartupConfig` |
| `19104` | El ID de grupo no es válido | Usa un grupo que exista en tu equipo |
| `19105` | El ID de etiqueta no es válido | Usa etiquetas que existan en tu equipo |
| `19106` | El ID de proxy no es válido | Usa un proxy que exista en tu equipo, u omite `proxyId` |
| `19107` | La versión del kernel del navegador no es válida | Elige una versión de `/env/advanced/ua/versions` |
| `19108` | La versión del user agent no es válida | Elige una versión de `/env/advanced/ua/versions` |
| `19109` | La versión del user agent no coincide con el user agent | Haz que `uaVersion` concuerde con `advancedSetting.ua`, o envía solo uno |
| `19110` | El formato de la URL personalizada no es válido | Envía una URL absoluta válida |
| `19111` | Firefox solo admite Windows y macOS | Elige Windows o macOS, o cambia a Chrome |
| `19112` | La clave de cifrado no está configurada, no se puede activar el cifrado del perfil | Configura una clave de cifrado del equipo, o envía `isEncrypt=0` |
| `19141` | Limitado a 100 caracteres, solo dígitos, letras y espacios | Acorta `accountInfo.otpSecret` y quita los demás caracteres |
| `19142` | Los perfiles cifrados de extremo a extremo no se pueden modificar | Usa el cliente de MoreLogin para los perfiles cifrados |
| `19143` | La versión del cliente es demasiado antigua para el kernel | Actualiza el cliente de escritorio de MoreLogin |
| `19147` | Límite de creación diaria superado | Mejora el plan para ampliar el límite |
| `19149` | No se seleccionó ningún tipo de caché | Selecciona al menos una clase de caché que borrar |
| `19159` | El sistema operativo no coincide con los ajustes avanzados | El SO no se puede cambiar al actualizar; deja `advancedSetting.os` como está guardado |
| `19160` | El tipo de navegador no coincide con los ajustes avanzados | El navegador no se puede cambiar al actualizar; deja `advancedSetting.vendor` como está guardado |
| `19175` | Coordenadas fuera del área de servicio | Elige coordenadas dentro del área admitida |
| `19193` | Quien compartió el perfil ha desactivado su edición | Pide al propietario que permita la edición |


### Cloud Storage (`39xxx`)

| Código | Descripción | Solución |
|  --- | --- | --- |
| `39001` | No se encontró la información de Cloud Storage | Comprueba que el equipo tiene Cloud Storage aprovisionado |
| `39011` | Archivo no encontrado | Verifica el ID del archivo |
| `39014` | La URL de acceso al archivo está vacía | Vuelve a registrar la subida |
| `39037` | El parámetro de extensión del archivo no es válido | Envía una extensión admitida |
| `39041` | Se alcanzó la cuota de almacenamiento | Elimina archivos para liberar espacio |
| `39044` | Nombre de archivo duplicado | Renombra el archivo |
| `39045` | Demasiadas subidas prefirmadas pendientes | Completa o abandona antes las subidas pendientes |
| `39046` | El archivo no se subió correctamente | Sube el archivo a la URL prefirmada antes de llamar a complete |
| `39047` | Cloud Storage ha caducado | Renueva Cloud Storage |
| `39048` | No se encontró la etiqueta de Cloud Storage | Usa una etiqueta devuelta por `/cloudstorage/tag/all` |
| `39049` | Los ID de etiqueta no pueden estar vacíos | Envía al menos una etiqueta; una lista vacía se rechaza |
| `39050` | El nombre del archivo supera los 60 caracteres | Acorta el nombre |
| `39051` | El tamaño del archivo debe ser mayor que 0 B y menor de 2 GB | Divide o comprime el archivo |


### Proxies (`14xxx`) y monedero (`20xxx`)

| Código | Descripción | Solución |
|  --- | --- | --- |
| `14003` | Falló la actualización del proxy, o el proxy no existe | Verifica el ID del proxy |
| `14017` | El proxy no se puede eliminar | Un proxy de plataforma en la nube sin caducar no se puede eliminar; espera a que caduque |
| `14023` | El tipo de proxy no existe | Usa un valor de servicio admitido |
| `14024` | El proxy no existe | Verifica los ID de proxy |
| `14519` | Los proxies dinámicos no se pueden modificar | Gestiona los proxies dinámicos fuera de los endpoints de proxy |
| `20018` | No se pudo leer el precio del producto | Reintenta más tarde e indica el `requestId` a soporte |
| `20029` | La cuenta del monedero no está disponible | Verifica el monedero del equipo |
| `20032` | Falló la consulta del saldo | Reintenta más tarde e indica el `requestId` a soporte |
| `20041` | Saldo insuficiente | Recarga el monedero |


### Runtimes de Cloud Browser (`40xxx`)

Los devuelven `/cloudbrowser/start`, `/cloudbrowser/stop` y `/cloudbrowser/connect`. Los códigos que se producen después de despachar la petición de inicio aparecen en `/cloudbrowser/page`, no en la respuesta de inicio.

| Código | Descripción | Solución |
|  --- | --- | --- |
| `40001` | El navegador en la nube ya está en ejecución | No hay nada que hacer; conéctate a la ejecución existente |
| `40002` | El navegador en la nube no se puede detener en su estado actual | Vuelve a leer `/cloudbrowser/page` y reintenta |
| `40003` | Falló la comprobación del proxy | Comprueba que el proxy vinculado es accesible |
| `40006` | Falló la operación del navegador en la nube | Reintenta; si falló el archivado, consulta `cloudBrowserArchiveStatus` |
| `40008` | No se encontró ningún navegador en la nube en ejecución | Inicia uno primero, o vuelve a leer `/cloudbrowser/page` |
| `40009` | No se puede conectar a una ejecución iniciada por otro miembro | Pide a ese miembro que la libere |
| `40010` | Falló la conexión al navegador en la nube | Reintenta; no se pudo emitir el token de acceso al escritorio |
| `40015` | El perfil no tiene ningún proxy vinculado | Vincula primero un proxy con `/env/setProxy/batch` |
| `40016` | No se pudo despachar la petición de inicio | Reintenta |
| `40020` | El navegador en la nube se está deteniendo | Espera a que termine la detención |
| `40021` | El navegador en la nube ya se está iniciando | No reenvíes; consulta `/cloudbrowser/page` |
| `40023` | El perfil está en uso | Cierra primero la otra sesión |
| `40024` | El navegador en la nube no se inició a tiempo | Vuelve a iniciarlo |
| `40025` | El proxy vinculado ya no existe | Vuelve a vincular un proxy |
| `40026` | El proxy vinculado ha caducado | Renueva o sustituye el proxy |
| `40027` | El proxy vinculado se está asignando todavía | Reintenta cuando termine la asignación |
| `40028` | Los proxies locales no están admitidos | Usa un proxy que no sea local |
| `40029` | Este tipo de proxy no está admitido | Usa un tipo de proxy admitido |
| `40037` | Los perfiles cifrados de extremo a extremo no pueden usar el navegador en la nube | Usa un perfil sin cifrar |


### Webhooks (`41xxx`)

Devueltos por los endpoints de configuración de webhooks cuando se rechaza la URL de callback.

| Código | Descripción | Solución |
|  --- | --- | --- |
| `41001` | La URL de callback debe ser una dirección HTTPS válida | Envía una URL HTTPS de 1024 caracteres como máximo, sin información de usuario ni fragmento y con un puerto válido, y comprueba que todas las direcciones que resuelve sean públicas |


### Autenticación de API (`35xxx`) y equipos (`12xxx`)

| Código | Descripción | Solución |
|  --- | --- | --- |
| `12002` | El equipo no existe | El equipo del miembro fue eliminado; contacta con soporte |
| `35002` | Falló la autenticación de la API | Revisa `client_id` (API ID) y `client_secret` (API key) |
| `35005` | La petición no tiene permiso de operación | El miembro está desactivado, o la IP que llama no pasa las listas de permitidos y denegados de la Open API |


## Códigos de estado HTTP

| Estado | Descripción |
|  --- | --- |
| `200` | Petición procesada (consulta el campo `code` para el resultado de negocio) |
| `401` | No autorizado: token de acceso inválido o caducado |
| `403` | Prohibido: permisos insuficientes |
| `429` | Demasiadas peticiones: límite de frecuencia superado |
| `500` | Error interno del servidor: contacta con soporte |


La puerta de enlace actual representa su propio rechazo por límite de frecuencia con el código de negocio `35000` y no establece explícitamente el HTTP `429`. Un proxy perimetral o una versión futura de la puerta de enlace podría devolver `429`, así que los clientes deberían gestionar ambas formas.

## Semántica de reintento y recuperación

| Categoría del fallo | ¿Reintentar? | Comportamiento requerido del cliente |
|  --- | --- | --- |
| Error de validación, permisos, saldo o función no admitida | No | Corrige la petición, el permiso, el saldo o el recurso elegido antes de reintentar |
| Límite de frecuencia (`35000`) | Sí, con condiciones | Retrocede con jitter; inspecciona el `code` del cuerpo incluso cuando el estado HTTP sea `200` |
| Fallo temporal del servidor o del servicio | Sí, con condiciones | Reintenta las lecturas; para escrituras, consulta primero el estado del recurso o de la tarea |
| Operación asíncrona aceptada | No reenvíes de inmediato | Consulta el endpoint de estado documentado hasta que haya éxito, fallo o timeout |
| Resultado desconocido tras un timeout de red | Comprueba el estado primero | No repitas a ciegas creaciones, compras, registros de subida ni creaciones de programaciones |


La API pública no documenta actualmente ninguna cabecera general de clave de idempotencia. Por eso las consultas de estado específicas de cada endpoint forman parte de una recuperación segura para las peticiones que cambian estado.

En las operaciones asíncronas, una respuesta con `code: 0` puede significar «aceptada», no «completada». Sigue la documentación de la operación para conocer su campo de estado y sus estados terminales.

Consulta la [matriz de reintentos y finalización de endpoints](/es/api-reference/getting-started/endpoint-behavior) para todas las operaciones y [Operaciones asíncronas](/es/api-reference/getting-started/async-operations) para los flujos de consulta y los estados terminales.

> **Consejo**: incluye siempre el `requestId` de la respuesta al contactar con soporte para acelerar el diagnóstico.