# Códigos de erro

Esta página lista os códigos de erro mais comuns retornados pela API do MoreLogin.

## Formato da resposta

Todas as respostas da API seguem este formato padrão:

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

| Campo | Tipo | Descrição |
|  --- | --- | --- |
| `code` | integer | `0` = sucesso, `>0` = erro |
| `msg` | string | Mensagem de erro (null quando há sucesso) |
| `data` | object | Dados da resposta |
| `requestId` | string | Identificador único da requisição para diagnóstico |


## Como um código identifica sua área

Os códigos não são alocados a partir de uma lista única. Cada área de produto tem sua própria faixa, então os dois ou três primeiros dígitos indicam qual subsistema rejeitou a requisição:

| Faixa | Área |
|  --- | --- |
| `14xxx` | Proxies |
| `15xxx` | Grupos e etiquetas |
| `19xxx` | Perfis de navegador |
| `20xxx` | Carteira, pedidos e cobrança |
| `21001` | Versão do cliente muito antiga |
| `33xxx` | Cloud Phone |
| `35xxx` | Autenticação da API e limites de taxa |
| `39xxx` | Cloud Storage |
| `40xxx` | Runtimes do Cloud Browser |
| `41xxx` | Configuração de webhooks |
| `99xxx` | Gateway e validação de requisições |


Cada operação lista os códigos que se sabe que ela retorna. Consulte as matrizes por produto vinculadas na [matriz de repetição e conclusão de endpoints](/pt/api-reference/getting-started/endpoint-behavior).

## Códigos de erro comuns

Retornados por qualquer operação, porque vêm da validação da requisição, das verificações de permissão e do gateway, e não da lógica de negócio.

| Código | Descrição | Solução |
|  --- | --- | --- |
| `0` | Sucesso | — |
| `21001` | Versão do cliente muito antiga | Atualize o cliente desktop do MoreLogin |
| `35000` | Requisições à API muito frequentes | Repita as operações elegíveis com recuo e jitter; consulte [Limites de taxa](/pt/api-reference/getting-started/rate-limits) |
| `99000` | Erro de sistema desconhecido | Tente mais tarde e informe o `requestId` ao suporte |
| `99001` | Parâmetros da requisição inválidos | Verifique o formato do corpo e os campos obrigatórios |
| `99002` | Permissão negada | Verifique as permissões da sua conta |
| `99003` | Exceção na requisição | Faça o ajuste de negócio necessário conforme `msg` |
| `99004` | Corpo da requisição muito grande | Reduza o corpo da requisição |
| `99005` | Já existe uma requisição igual em andamento | Aguarde a requisição em curso terminar antes de repetir |
| `99006` | Requisição inválida | Verifique o método HTTP, os cabeçalhos e o corpo |
| `99007` | O IP da requisição não está na lista de permitidos | Adicione o IP chamador à lista de permitidos |
| `99008` | Cota de requisições por IP ou dispositivo excedida | Reduza o volume de requisições deste IP ou dispositivo |
| `99009` | Requisições em excesso | Recue com jitter e repita |
| `99011` | O carimbo de tempo da requisição expirou | Reenvie com um carimbo de tempo atual |
| `99012` | É necessária permissão de custos | Use a conta do proprietário da equipe, ou conceda a permissão de custos |


### Cloud Phone (`33xxx`)

| Código | Descrição | Solução |
|  --- | --- | --- |
| `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` | O Cloud Phone não existe | Verifique o ID do Cloud Phone e se ele pertence à sua equipe |
| `33301` | O Cloud Phone não está ligado | Ligue-o e aguarde até um estado executável |
| `33308` | Outro membro está usando, não é possível desligar | Tente novamente quando o outro membro liberar |
| `33309` | Outro membro está usando, não é possível conectar | Tente novamente quando o outro membro liberar |
| `33315` | Conta em débito, Cloud Phone congelado | Recarregue a carteira |
| `33316` | Não há perfis disponíveis suficientes | Faça upgrade do plano |
| `33317` | A permissão do perfil foi revogada | Peça a um administrador para conceder acesso |
| `33318` | Saldo insuficiente para ligar | Recarregue a carteira |
| `33321` | O perfil está indisponível | Verifique o estado do perfil antes de repetir |
| `33322` | Verificação do proxy em andamento | Consulte até a verificação terminar |
| `33323` | O perfil está iniciando | Aguarde o início terminar; não reenvie |
| `33324` | O perfil já está em execução | Nada a fazer |
| `33325` | O perfil está desativado | Reative-o antes de usar |
| `33331` | Novo dispositivo em um clique em andamento, não é possível desligar | Aguarde a conclusão |
| `33332` | Reinício em andamento, não é possível desligar | Aguarde a conclusão |
| `33333` | Redefinição em andamento, não é possível desligar | Aguarde a conclusão |
| `33338`–`33345` | País, fuso horário, idioma, longitude ou latitude ausente ou inválido | Consulte a [tabela de países e fusos horários](/pt/api-reference/appendix/country-time-zone) |
| `33346` | O SKU não está mais à venda | Escolha outro `skuId` |
| `33347` | O modelo exige a versão mais recente do cliente para Windows | Atualize o cliente desktop do MoreLogin |
| `33367` | Em manutenção, não é possível ligar | Consulte os avisos do sistema para a janela de recuperação |
| `33376` | A cobrança mensal expirou | Renove a assinatura |
| `33398`–`33400` | Longitude, latitude ou altitude fora da faixa | Longitude −180…180, latitude −90…90, altitude −50000…100000 |
| `33401` | O Cloud Phone não suporta esta operação | Use um modelo compatível |
| `33407` | Cota do pacote de concorrência excedida | Aguarde uma vaga ou aumente a cota |
| `33408` | O formato do número de telefone é inválido | Comece com `+`, código do país de 1–3 dígitos excluindo 86, e 8–14 dígitos no total |
| `33418` | O arquivo de transmissão não existe ou é inválido | Envie com `uploadType=2` e use o `fileId` retornado |
| `33419` | O formato do arquivo de transmissão não é suportado | Envie um MP4 por `/cloudphone/uploadFile` |
| `33005` | A instalação do app falhou | Repita e verifique o espaço de armazenamento do dispositivo |
| `33014` | Operação muito frequente | Recue e repita |
| `33714` | O app não existe ou foi retirado | Atualize a biblioteca de apps |
| `33814` | O modelo de RPA não existe | Liste os modelos novamente e use um `templateId` atual |
| `33818` | O formato do parâmetro do modelo de RPA é inválido | Envie `templateParameter` como uma string JSON escapada |
| `33303` | A criação do Cloud Phone falhou | Consulte `/cloudphone/page` antes de repetir; não reenvie às cegas |
| `33320` | O proxy vinculado a este Cloud Phone foi excluído | Revincule um proxy com `/cloudphone/setProxy` |
| `33326` | Outro membro está usando, não é possível substituir o dispositivo | Tente novamente quando o outro membro liberar |
| `33350` | Não foi possível ativar o ADB em alguns Cloud Phones | Esses telefones não estão em execução ou não suportam ADB; releia o estado e repita apenas para eles |
| `33507` | O arquivo não existe no dispositivo | Verifique o caminho; a requisição de download percorre o diretório pai antes de transferir |


Operações de instalação e de energia podem retornar ainda um código mapeado pelo serviço nas faixas `33001`–`33033`, `33500`–`33520`, `33700`–`33724` ou `33900`–`33910`. Qual deles é alcançável depende do serviço que atende o dispositivo, então as operações não os listam individualmente.

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

| Código | Descrição | Solução |
|  --- | --- | --- |
| `19001` | O nome do perfil já existe | Escolha um nome único, ou omita `envName` para gerar um |
| `19002` | A criação do perfil falhou a jusante | Confirme com `/env/page` antes de repetir |
| `19004` | O formato do user agent é inválido | Envie um `advancedSetting.ua` que possa ser interpretado |
| `19005` | O formato dos cookies é inválido | Envie `cookies` como uma string JSON de array escapada |
| `19039` | Perfil não encontrado | Verifique `envId` / `uniqueId` e se pertence à sua equipe |
| `19063` | Limite de quantidade de perfis atingido | Exclua perfis ou faça upgrade do plano |
| `19064` | Sem permissão para este grupo | Peça acesso ao grupo a um administrador |
| `19065` | Sem permissão para este perfil | Peça acesso ao perfil a um administrador |
| `19099` | Não há perfis disponíveis suficientes, o uso está restrito | Faça upgrade do plano |
| `19100` | O ID da plataforma é inválido | Use um `platformId` retornado por `/system/platform/list` |
| `19101` | O ID do site é inválido | Use um `siteId` retornado por `/system/platform/list` |
| `19102` | A URL de plataforma personalizada não pode ficar vazia | Envie `platformUrl` quando `platformId` for `9999` |
| `19103` | O formato da URL de abertura automática é inválido | Envie URLs absolutas válidas em `afterStartupConfig` |
| `19104` | O ID do grupo é inválido | Use um grupo que exista na sua equipe |
| `19105` | O ID da etiqueta é inválido | Use etiquetas que existam na sua equipe |
| `19106` | O ID do proxy é inválido | Use um proxy que exista na sua equipe, ou omita `proxyId` |
| `19107` | A versão do kernel do navegador é inválida | Escolha uma versão em `/env/advanced/ua/versions` |
| `19108` | A versão do user agent é inválida | Escolha uma versão em `/env/advanced/ua/versions` |
| `19109` | A versão do user agent não corresponde ao user agent | Faça `uaVersion` concordar com `advancedSetting.ua`, ou envie apenas um |
| `19110` | O formato da URL personalizada é inválido | Envie uma URL absoluta válida |
| `19111` | O Firefox suporta apenas Windows e macOS | Escolha Windows ou macOS, ou mude para o Chrome |
| `19112` | A chave de criptografia não está configurada, não é possível ativar a criptografia do perfil | Configure uma chave de criptografia da equipe, ou envie `isEncrypt=0` |
| `19141` | Limitado a 100 caracteres, apenas dígitos, letras e espaços | Encurte `accountInfo.otpSecret` e remova os demais caracteres |
| `19142` | Perfis criptografados ponta a ponta não podem ser modificados | Use o cliente do MoreLogin para perfis criptografados |
| `19143` | A versão do cliente é muito antiga para o kernel | Atualize o cliente desktop do MoreLogin |
| `19147` | Limite diário de criação excedido | Faça upgrade do plano para aumentar o limite |
| `19149` | Nenhum tipo de cache foi selecionado | Selecione ao menos uma classe de cache para limpar |
| `19159` | O sistema operacional não corresponde às configurações avançadas | O SO não pode ser alterado na atualização; mantenha `advancedSetting.os` como está armazenado |
| `19160` | O tipo de navegador não corresponde às configurações avançadas | O navegador não pode ser alterado na atualização; mantenha `advancedSetting.vendor` como está armazenado |
| `19175` | Coordenadas fora da área de serviço | Escolha coordenadas dentro da área suportada |
| `19193` | Quem compartilhou desativou a edição deste perfil | Peça ao proprietário para permitir a edição |


### Cloud Storage (`39xxx`)

| Código | Descrição | Solução |
|  --- | --- | --- |
| `39001` | Informações do Cloud Storage não encontradas | Verifique se o Cloud Storage está provisionado para a equipe |
| `39011` | Arquivo não encontrado | Verifique o ID do arquivo |
| `39014` | A URL de acesso ao arquivo está vazia | Registre o envio novamente |
| `39037` | O parâmetro de extensão do arquivo é inválido | Envie uma extensão suportada |
| `39041` | Cota de armazenamento atingida | Exclua arquivos para liberar espaço |
| `39044` | Nome de arquivo duplicado | Renomeie o arquivo |
| `39045` | Muitos envios pré-assinados pendentes | Conclua ou abandone os envios pendentes primeiro |
| `39046` | O arquivo não foi enviado com sucesso | Envie o arquivo para a URL pré-assinada antes de chamar complete |
| `39047` | O Cloud Storage expirou | Renove o Cloud Storage |
| `39048` | Etiqueta do Cloud Storage não encontrada | Use uma etiqueta retornada por `/cloudstorage/tag/all` |
| `39049` | Os IDs de etiqueta não podem ficar vazios | Envie ao menos uma etiqueta; uma lista vazia é rejeitada |
| `39050` | O nome do arquivo passa de 60 caracteres | Encurte o nome |
| `39051` | O tamanho do arquivo precisa ser maior que 0 B e menor que 2 GB | Divida ou compacte o arquivo |


### Proxies (`14xxx`) e carteira (`20xxx`)

| Código | Descrição | Solução |
|  --- | --- | --- |
| `14003` | A atualização do proxy falhou, ou o proxy não existe | Verifique o ID do proxy |
| `14017` | O proxy não pode ser excluído | Um proxy de plataforma na nuvem não expirado não pode ser removido; aguarde a expiração |
| `14023` | O tipo de proxy não existe | Use um valor de serviço suportado |
| `14024` | O proxy não existe | Verifique os IDs de proxy |
| `14519` | Proxies dinâmicos não podem ser modificados | Gerencie proxies dinâmicos fora dos endpoints de proxy |
| `20018` | Não foi possível ler o preço do produto | Tente mais tarde e informe o `requestId` ao suporte |
| `20029` | A conta da carteira está indisponível | Verifique a carteira da equipe |
| `20032` | A consulta de saldo falhou | Tente mais tarde e informe o `requestId` ao suporte |
| `20041` | Saldo insuficiente | Recarregue a carteira |


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

Retornados por `/cloudbrowser/start`, `/cloudbrowser/stop` e `/cloudbrowser/connect`. Códigos gerados depois que a requisição de início é despachada aparecem em `/cloudbrowser/page`, não na resposta de início.

| Código | Descrição | Solução |
|  --- | --- | --- |
| `40001` | O navegador na nuvem já está em execução | Nada a fazer; conecte-se à execução existente |
| `40002` | O navegador na nuvem não pode ser encerrado no estado atual | Releia `/cloudbrowser/page` e repita |
| `40003` | A verificação do proxy falhou | Verifique se o proxy vinculado está acessível |
| `40006` | A operação do navegador na nuvem falhou | Repita; se o arquivamento falhou, consulte `cloudBrowserArchiveStatus` |
| `40008` | Nenhum navegador na nuvem em execução foi encontrado | Inicie um primeiro, ou releia `/cloudbrowser/page` |
| `40009` | Não é possível conectar a uma execução iniciada por outro membro | Peça a esse membro para liberá-la |
| `40010` | A conexão com o navegador na nuvem falhou | Repita; não foi possível emitir o token de acesso ao desktop |
| `40015` | O perfil não tem proxy vinculado | Vincule primeiro um proxy com `/env/setProxy/batch` |
| `40016` | Não foi possível despachar a requisição de início | Repita |
| `40020` | O navegador na nuvem está sendo encerrado | Aguarde o encerramento terminar |
| `40021` | O navegador na nuvem já está iniciando | Não reenvie; consulte `/cloudbrowser/page` |
| `40023` | O perfil está em uso | Feche a outra sessão primeiro |
| `40024` | O navegador na nuvem não iniciou em tempo | Inicie-o novamente |
| `40025` | O proxy vinculado não existe mais | Revincule um proxy |
| `40026` | O proxy vinculado expirou | Renove ou substitua o proxy |
| `40027` | O proxy vinculado ainda está sendo alocado | Repita quando a alocação terminar |
| `40028` | Proxies locais não são suportados | Use um proxy que não seja local |
| `40029` | Este tipo de proxy não é suportado | Use um tipo de proxy suportado |
| `40037` | Perfis criptografados ponta a ponta não podem usar o navegador na nuvem | Use um perfil sem criptografia |


### Webhooks (`41xxx`)

Retornados pelos endpoints de configuração de webhooks quando a URL de callback é rejeitada.

| Código | Descrição | Solução |
|  --- | --- | --- |
| `41001` | A URL de callback deve ser um endereço HTTPS válido | Envie uma URL HTTPS com no máximo 1024 caracteres, sem informações de usuário nem fragmento e com porta válida, e verifique se todos os endereços resolvidos são públicos |


### Autenticação da API (`35xxx`) e equipes (`12xxx`)

| Código | Descrição | Solução |
|  --- | --- | --- |
| `12002` | A equipe não existe | A equipe do membro foi removida; entre em contato com o suporte |
| `35002` | A autenticação da API falhou | Verifique `client_id` (API ID) e `client_secret` (API key) |
| `35005` | A requisição não tem permissão de operação | O membro está desativado, ou o IP chamador não passa nas listas de permissão e bloqueio da Open API |


## Códigos de status HTTP

| Status | Descrição |
|  --- | --- |
| `200` | Requisição processada (verifique o campo `code` para o resultado de negócio) |
| `401` | Não autorizado — token de acesso inválido ou expirado |
| `403` | Proibido — permissões insuficientes |
| `429` | Requisições em excesso — limite de taxa atingido |
| `500` | Erro interno do servidor — entre em contato com o suporte |


O gateway atual representa a própria rejeição por limite de taxa com o código de negócio `35000` e não define explicitamente o HTTP `429`. Um proxy de borda ou uma versão futura do gateway ainda pode retornar `429`, então os clientes devem tratar as duas formas.

## Semântica de repetição e recuperação

| Categoria da falha | Repetir? | Comportamento exigido do cliente |
|  --- | --- | --- |
| Erro de validação, permissão, saldo ou recurso não suportado | Não | Corrija a requisição, a permissão, o saldo ou o recurso escolhido antes de repetir |
| Limite de taxa (`35000`) | Sim, condicionalmente | Recue com jitter; verifique o `code` do corpo mesmo quando o status HTTP for `200` |
| Falha temporária do servidor ou do serviço | Sim, condicionalmente | Repita leituras; para escritas, consulte primeiro o estado do recurso ou da tarefa |
| Operação assíncrona aceita | Não reenvie imediatamente | Consulte o endpoint de status documentado até sucesso, falha ou timeout |
| Resultado desconhecido após um timeout de rede | Verifique o estado primeiro | Não repita às cegas criação, compra, registro de envio nem criação de agendamento |


A API pública atualmente não documenta um cabeçalho geral de chave de idempotência. Por isso as consultas de estado específicas de cada endpoint fazem parte da recuperação segura para requisições que alteram estado.

Em operações assíncronas, uma resposta com `code: 0` pode significar «aceita», não «concluída». Siga a documentação da operação para o campo de status e os estados terminais dela.

Consulte a [matriz de repetição e conclusão de endpoints](/pt/api-reference/getting-started/endpoint-behavior) para todas as operações e [Operações assíncronas](/pt/api-reference/getting-started/async-operations) para os fluxos de consulta e os estados terminais.

> **Dica**: sempre inclua o `requestId` da resposta ao entrar em contato com o suporte para agilizar o diagnóstico.