Erros e limites para quem integra

O que cada resposta de erro do proxy, da Agent API, do MCP Gateway e da API de integração significa, e os limites de cada plano.

Este artigo junta, do ponto de vista de quem integra, os erros que mais aparecem e os limites que os causam. A lista completa de erros de cada rota da API está na referência, no painel em /api-docs.

Proxy

O tráfego do agente passa pelo proxy (proxy.4keyless.io:8080). Os erros do próprio 4Keyless vêm marcados por cabeçalho; sem o cabeçalho, a resposta é do sistema de destino.

Resposta	Significado	O que fazer
`407 Proxy Authentication Required`	Chave ausente, inválida, expirada ou de agente desativado.	Confira `Proxy-Authorization` ou a URL de proxy.
`403` com `X-4Keyless-Blocked: true`	A liberação bloqueou o acesso (`access_blocked`), o horário não é permitido (`access_out_of_schedule`) ou o pedido de aprovação foi negado ou ficou sem resposta. `X-4Keyless-System` traz o acesso.	Não tente contornar. Avise quem administra a conta.
Demora e depois sucesso ou `403`	A liberação pede aprovação; a requisição espera alguém responder no painel.	Use timeout de pelo menos 120 segundos no cliente.
`429` com `X-4Keyless-Limited: true`	A cota mensal de transferência do plano acabou (`transfer_limit_exceeded`).	Pare e avise; a cota volta no dia 1.
`502` com `X-4Keyless-Egress-Error`	O local da conexão falhou antes de a requisição chegar ao destino.	Veja o código abaixo; tente outro local da conexão com `X-4Keyless-Exit-Proxy`.
`403` sem `X-4Keyless-Blocked`	O próprio sistema de destino recusou. Em portais públicos, o motivo comum é o user agent de navegador headless.	Use um user agent de Chrome comum.
`401` ou `403` do destino num acesso OAuth	A conexão OAuth guardada precisa de atenção (reconectar, por exemplo).	Avise quem administra; o agente não resolve.
Erro de certificado no cliente	O cliente não confia no certificado do 4Keyless, ou o host está em `NO_PROXY`.	Veja Ligar um agente de IA.

Códigos de X-4Keyless-Egress-Error:

Código	Significado
`exit_proxy_unreachable`	O local da conexão está fora do ar ou recusou a conexão.
`exit_proxy_upstream_unreachable`	O destino não respondeu por aquele local da conexão; o IP de saída pode estar bloqueado pelo destino.
`localproxy_no_nodes`	O local é o Proxy local e nenhum computador da empresa está conectado. Veja Proxy local.
`localproxy_node_failed`	Os computadores do Proxy local não conseguiram conectar ao destino.
`localproxy_destination_blocked`	O Proxy local recusa destinos da rede interna e a porta 25.
`localproxy_plain_http`	O Proxy local só leva HTTPS.
`localproxy_tls_unverified`	O certificado do destino não pôde ser verificado; nada foi enviado.

Para navegador (Accept: text/html), essas respostas vêm como uma página em português; para os demais clientes, como JSON com error e message em inglês.

Agent API

https://agent.4keyless.io, com Authorization: Bearer <chave>. Os erros vêm como {"error": "<frase>"}. POST /api/runs responde {"error": "<código>", "message": "<frase>"}, para quem chama decidir pelo código.

MCP Gateway

Erros de ferramenta começam pelo código, seguido da explicação, por exemplo policy_denied: a política não libera este titular. Os mais comuns:

Código	Significado
`policy_denied`	A liberação não cobre este acesso ou este titular.
`credential_group_required`	Há mais de um titular liberado e nenhum padrão. A mensagem lista as opções; repita com o `credential_group_id`.
`plan_feature_required`	O plano não inclui o recurso, por exemplo execução no servidor no plano Free.
`idempotency_conflict`	A mesma chave de idempotência já foi usada por outro agente.

API de integração e de parceiros

Toda resposta segue { "data": null, "error": { "code", "message" } }.

Resposta	Significado
`400 validation_error`	Corpo ou query fora do schema da rota.
`401 unauthorized`	Key inexistente, adulterada ou com formato errado. Sem detalhe, de propósito.
`403 delegation_blocked`	Key válida, mas bloqueada. O `reason` diz o motivo: `key_expired`, `key_revoked`, `user_inactive`, `ip_not_allowed`, `tenant_suspended`, `partner_suspended`, `partner_terminated`, `license_required`.
`403 insufficient_scope`	A key não tem o escopo da rota (`x-scope` na referência).
`403 route_not_allowed`	A rota não está disponível para keys de integração.
`403 plan_limit_reached`	Criar o recurso passaria do limite do plano (agentes ou acessos). `details` traz o recurso e o máximo.
`403 plan_feature_required`	O plano não inclui o recurso (aprovação, OAuth, scripts no servidor, assinatura no Desktop, execução no servidor).
`404 not_found`	Recurso inexistente nesta conta. Em toda rota: a API está desligada no ambiente.
`409 idempotency_conflict`	`Idempotency-Key` repetida com outro corpo (API de parceiros).
`429 rate_limited`	Limite por minuto da key ou do IP.

Execuções

Ao disparar uma execução (POST /api/v1/runs, POST /api/runs na Agent API ou uma ferramenta op__ no MCP):

Resposta	Significado
`400 agent_required`	Pela API de integração, falta o `agent_id`.
`400 credential_group_required`	Há vários titulares liberados e nenhum padrão; a resposta traz as opções.
`403 plan_feature_required`	O plano Free não executa operações no servidor. Use a extensão, que executa no navegador.
`429 QuotaExceeded`	A empresa já tem 3 execuções no servidor em andamento. Espere uma terminar.
`429 MonthlyQuotaExceeded`	A cota mensal de tempo de execução no servidor acabou. Volta no dia 1.
Execução falha com `captcha_quota_exceeded`	A cota mensal de captchas resolvidos acabou. Volta no dia 1.

Limites por plano

Valores padrão de cada plano. A sua conta pode ter limites diferentes (agentes adicionais comprados ou condições negociadas): os valores em vigor estão no painel, em Faturamento, e em GET /api/v1/billing/status (escopo billing:read). As cotas mensais reiniciam no dia 1, em UTC.

	Free	Starter	Growth	Enterprise
Agentes	2	5	15	sem limite
Acessos ativos	2	5	sem limite	sem limite
Transferência pelo proxy, por mês	1 GiB	sem limite	sem limite	sem limite
Retenção do registro de acessos	14 dias	30 dias	365 dias	sem limite prático
Execução de operações no servidor	não	sim	sim	sim
Tempo de execução no servidor, por mês	não se aplica	25 min, ou 25 min por usuário do painel, o que for maior	25 min, ou 25 min por usuário do painel, o que for maior	sem limite
Captchas resolvidos, por mês	100	100, ou 100 por usuário do painel, o que for maior	100, ou 100 por usuário do painel, o que for maior	sem limite
Aprovação antes do uso	não	não	sim	sim
Scripts executados no servidor	não	sim	sim	sim
Credenciais OAuth	não	não	sim	sim
Assinatura no Desktop	não	não	sim	sim

Operações executadas no navegador da pessoa, pela extensão, não contam no tempo de execução. Agente desativado continua ocupando vaga; só agente excluído libera.

Limites que valem em todos os planos

Limite	Valor
API de integração	120 chamadas por minuto por key, 300 por IP, 60 escritas por key
API de parceiros	120 chamadas por minuto por key, 300 por IP
Execuções no servidor ao mesmo tempo	3 por empresa
Assinaturas pelo Desktop e códigos 2FA, por agente	o campo Rate limit (RPM) do agente; 60 por minuto quando vazio
Código de login por e-mail	8 caracteres, 10 minutos, 5 tentativas
Sessão do agente humano	7 dias
Token delegado	de 60 a 900 segundos, padrão 300