Catálogo de erros
Gerada dos catálogos de mensagens da API (Zoppy-crm/zoppy-connect@f1ae3a72be71). Todo erro da API vem como JSON (application/json) no formato problem+json:
{ "type": "connect.route_not_allowed", "title": "Essa rota não está liberada no manifesto do conector.", "status": 403, "detail": "Essa rota não está liberada no manifesto do conector.", "requestId": "01JC5R6Z8T2Q9M3V7X1B4N0K2P", "meta": { "host": "partners.zoppy.com.br", "method": "DELETE" }}O type é o código estável, em inglês; a mensagem é em português e é a que a tela mostra. Os {marcadores} são preenchidos com o meta. Passe o requestId ao suporte. No código do conector, uma recusa do gateway chega como ConnectGatewayError com o mesmo code (SDK). Status — quando o código não sai como resposta HTTP própria (aparece no passo da execução ou varia).
Acesso ao Connect
Seção intitulada “Acesso ao Connect”| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
connect.access_token_not_allowed |
403 | Esta operação só pode ser feita na tela do Zoppy Connect, não pela CLI. | — |
connect.feature_disabled |
403 | O Zoppy Connect não está liberado para esta loja. | Peça ao time da Zoppy para liberar o Connect na loja (feature ligada no app admin). |
connect.feature_unverifiable |
403 | Não conseguimos confirmar que o Zoppy Connect continua liberado para esta loja. Abra a tela do Zoppy Connect uma vez ou reconecte o acesso à Zoppy e tente de novo. | — |
connect.features_unavailable |
503 | Não conseguimos confirmar o acesso ao Zoppy Connect agora. Tente novamente em instantes. | — |
connect.forbidden_role |
403 | Só administradores da loja podem usar o Zoppy Connect. | Entre com um usuário MASTER ou ADMIN da loja. |
connect.insufficient_scope |
403 | Este acesso não libera esta operação no Zoppy Connect. Entre de novo e autorize o acesso pedido. | — |
connect.missing_company |
403 | Escolha uma loja na Zoppy antes de abrir o Zoppy Connect. | — |
connect.restricted_token |
403 | Este acesso não abre o Zoppy Connect. Entre na Zoppy com seu usuário. | — |
connect.terms_master_only |
403 | Só um usuário MASTER da loja pode aceitar os termos do Zoppy Connect. | — |
connect.terms_not_accepted |
403 | Um MASTER da loja precisa aceitar os termos do Zoppy Connect antes do primeiro uso. | — |
connect.unauthorized |
401 | Sua sessão expirou. Entre de novo na Zoppy. | — |
Conectores, versões, segredos e acesso à Zoppy
Seção intitulada “Conectores, versões, segredos e acesso à Zoppy”| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
connect.agent_not_available |
422 | Estes agentes locais não existem nesta loja ou foram revogados: {list} | O manifesto aponta para um agente revogado ou de outra loja. Pareie um agente e peça à IA para atualizar o agentId. |
connect.confirmation_refused |
409 | A confirmação expirou ou não vale mais para este conector. Gere a prévia de novo. | — |
connect.confirmation_stale |
409 | O conector mudou depois da prévia. Gere a prévia de novo e confirme. | Algo mudou depois da prévia: abra a prévia de novo e confirme. |
connect.connector_not_found |
404 | Não encontramos esse conector. | — |
connect.connector_transition_refused |
409 | Não dá para fazer isso com o conector no estado em que ele está agora. | — |
connect.host_not_declared |
422 | Estes hosts não estão no manifesto do conector: {list} | — |
connect.invalid_code |
422 | O código do conector não compila: {detail} | — |
connect.invalid_manifest |
422 | O manifesto do conector tem problemas: {detail} | — |
connect.not_rehearsed |
409 | Ensaie esta versão lendo a origem inteira antes de publicar. | Rode um ensaio completo limpo da versão em edição e publique de novo. |
connect.secret_missing |
409 | Falta preencher um segredo do conector. | — |
connect.secret_not_declared |
422 | O manifesto do conector não pede esse segredo. | — |
connect.system_logo_not_found |
404 | Esse sistema ainda não tem logo. | — |
connect.system_logo_refused |
422 | O logo precisa ser um PNG com fundo transparente, de 128 pixels ou mais de lado e até 512 KB. | — |
connect.system_not_found |
404 | Não encontramos esse sistema no catálogo. | — |
connect.version_conflict |
409 | O conector mudou enquanto você editava. Abra a versão mais nova e tente de novo. | Outra versão foi guardada enquanto você editava: abra a mais nova e repita a mudança em cima dela. |
connect.version_not_found |
404 | Não encontramos essa versão do conector. | — |
connect.write_without_lookup |
409 | O último ensaio desta versão criou registros sem antes consultar se eles já existiam ({list}). Toda escrita precisa ser idempotente: corrija o conector para buscar pela chave natural antes de criar e ensaie de novo. | Peça à IA para buscar o registro pela chave natural antes de criar (ou atualizar pelo id) e ensaie de novo. |
connect.zoppy_free_tier |
403 | O Zoppy Connect precisa de um plano pago da Zoppy para acessar os dados da loja. | A loja precisa de um plano pago da Zoppy. |
connect.zoppy_token_inactive |
409 | O acesso do Zoppy Connect à Zoppy foi desativado. Gere um novo acesso para religar os conectores. | Um administrador abre o Connect: ele gera um acesso novo e oferece religar os conectores. |
connect.zoppy_token_missing |
409 | O acesso à Zoppy ainda não foi gerado para esta loja. | — |
connect.zoppy_token_outside_zoppy |
403 | O acesso à Zoppy só pode ser usado em chamadas para a Zoppy. | — |
connect.zoppy_token_unavailable |
503 | Não conseguimos gerar o acesso à Zoppy agora. Tente novamente em instantes. | — |
Execuções, ensaios e quarentena
Seção intitulada “Execuções, ensaios e quarentena”| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
connect.access_incomplete |
409 | Falta preencher o acesso do conector antes de ensaiar: {list} | Preencha na tela os segredos listados (o formulário de acesso fica fora do chat) e ensaie de novo. |
connect.connector_not_enabled |
409 | Ligue o conector antes de rodar ou reprocessar. | — |
connect.connector_without_version |
409 | Este conector ainda não tem uma versão para rodar. | — |
connect.hosts_awaiting_approval |
409 | Aprove estes hosts antes de ensaiar: {list} | Uma pessoa da loja aprova os hosts novos na tela do conector (prévia e confirmação) antes do ensaio. |
connect.quarantine_empty |
422 | Não há registros abertos na quarentena para reprocessar. | — |
connect.quarantine_item_not_found |
404 | Este registro não está mais na quarentena. | — |
connect.quarantine_record_not_object |
422 | Só dá para corrigir campos de um registro que tem campos. | — |
connect.run_in_progress |
409 | Este conector já tem uma execução em andamento. Espere ela terminar. | Espere a execução em andamento terminar. |
connect.run_not_found |
404 | Não encontramos esta execução. | — |
connect.writes_awaiting_confirmation |
409 | Este conector tem uma escrita guardada esperando confirmação. Confirme ou descarte a escrita antes de rodar de novo. | — |
Gateway (chamadas do conector)
Seção intitulada “Gateway (chamadas do conector)”| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
connect.blocked_address |
403 | Esse endereço aponta para uma rede interna e foi bloqueado. | O host resolveu para um IP interno. Um sistema dentro da rede da loja só é alcançado pelo agente local. |
connect.emergency_pause_active |
409 | Já existe uma pausa de emergência ativa nesse escopo. | — |
connect.emergency_pause_not_found |
404 | Essa pausa de emergência não existe. | — |
connect.external_writes_not_allowed |
403 | Esse conector não pode escrever no outro sistema. | O conector tentou escrever sem externalWrites: true no manifesto. Peça à IA para revisar. |
connect.gateway_not_wired |
503 | Erro inesperado. Tente novamente em instantes. | — |
connect.host_not_allowed |
403 | Esse endereço não está no manifesto do conector. | O código chamou um host fora de hosts. Peça à IA para corrigir o manifesto; o host novo precisa de aprovação. |
connect.host_not_approved |
403 | Esse endereço ainda não foi aprovado por uma pessoa da loja. | Aprove o host na tela do conector. |
connect.invalid_run_token |
401 | Execução sem credencial válida. | — |
connect.invalid_target |
422 | Esse endereço não pode ser chamado pelo conector. | — |
connect.operator_unauthorized |
401 | Acesso restrito ao time da plataforma. | — |
connect.paused |
423 | O Zoppy Connect está pausado para este conector. | O conector (ou a loja) está pausado. Veja o motivo na tela do conector. |
connect.response_too_large |
502 | A resposta do outro sistema passou do limite da execução. | Peça páginas menores ao outro sistema (a IA ajusta o código). |
connect.route_not_allowed |
403 | Essa rota não está liberada no manifesto do conector. | Método ou caminho fora de routes (ou um DELETE na Zoppy, sempre recusado). Peça à IA para ajustar o código ou o manifesto. |
connect.run_not_running |
409 | Essa execução já terminou. | — |
connect.runner_failed |
502 | A execução do conector falhou antes de terminar. Tente novamente em instantes. | — |
connect.secret_reserved |
403 | Esse acesso é reservado e não pode ser usado pelo código do conector. | — |
connect.upstream_failed |
502 | O outro sistema não respondeu. | O outro sistema não respondeu a tempo. Confira se ele está no ar; a próxima execução retoma do cursor. |
Agente local
Seção intitulada “Agente local”| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
connect.agent_busy |
— | O agente local está ocupado com outras chamadas. Tente de novo em instantes. | — |
connect.agent_connection_lost |
— | A conexão com o agente local caiu com a chamada em andamento: ela pode ter chegado ao sistema ({detail}). Confira lá antes de repetir. | — |
connect.agent_contract_unsupported |
426 | Essa versão do agente não fala com a Zoppy. Atualize o agente para a versão mais nova. | Atualize o agente: zoppy-agent update. |
connect.agent_cut_unauthorized |
401 | Pedido de corte do agente sem autorização válida. | — |
connect.agent_error |
— | O agente local falhou: {detail}. | — |
connect.agent_invalid_target |
400 | Endereço inválido para o agente local: {reason}. | — |
connect.agent_method_not_allowed |
405 | Pelo agente local só GET e HEAD são permitidos (veio {method}). | — |
connect.agent_not_allowed |
— | O agente local recusou: {detail}. Libere o endereço na lista do agente, na máquina onde ele roda. | Na máquina do agente, libere o banco ou a API na lista local (zoppy-agent allow add) e confira com zoppy-agent allow check. |
connect.agent_not_found |
404 | Esse agente local não existe na sua loja. | — |
connect.agent_not_in_manifest |
400 | O endereço {target} não está em nenhum agente do manifesto. | — |
connect.agent_offline |
503 | O agente local não está conectado: a máquina está desligada, sem internet, ou o serviço do agente parou. | Siga o diagnóstico de agente fora do ar da página do agente local. |
connect.agent_pairing_bad_request |
400 | O pedido de pareamento do agente veio inválido: {reason}. | — |
connect.agent_pairing_code_invalid |
400 | Código de pareamento inválido, já usado ou vencido. Gere outro na tela do agente local. | Gere um código novo na tela (vale 30 minutos e uma vez só). |
connect.agent_pairing_rate_limited |
429 | Tentativas demais de parear. Espere {retryAfterSeconds} segundos e tente de novo. | — |
connect.agent_protocol_error |
— | O agente local respondeu fora do contrato: {detail}. | — |
connect.agent_response_too_large |
502 | A resposta do agente local passou do limite de {maxBytes} bytes. | — |
connect.agent_revoked |
403 | O agente local foi revogado. Instale e pareie um agente novo e aponte o conector para ele. | Instale e pareie um agente novo e aponte o conector para ele. |
connect.agent_secrets_unavailable |
503 | Não conseguimos ler os segredos do conector para falar com o banco. Tente de novo em instantes. | — |
connect.agent_sql_auth_failed |
— | O banco recusou o usuário ou a senha: {detail}. | Confira o usuário e a senha do banco nos segredos do conector (o usuário só leitura criado pelo DBA). |
connect.agent_sql_failed |
— | O banco devolveu erro na consulta: {detail}. | — |
connect.agent_sql_not_read_only |
400 | A consulta não é só leitura: {detail}. | A consulta precisa ser um único SELECT (ou WITH ... SELECT). Peça à IA para corrigir. |
connect.agent_target_unreachable |
— | O agente não conseguiu chegar ao sistema na rede da loja: {detail}. | A máquina do agente não chega ao banco ou à API: confira host, porta, firewall interno e certificado. |
connect.agent_timeout |
— | O agente local não respondeu a tempo: {detail}. | — |
connect.agent_unsupported |
— | Essa versão do agente local não sabe fazer isso: {detail}. Atualize o agente. | Atualize o agente: zoppy-agent update. |
Escritas guardadas
Seção intitulada “Escritas guardadas”| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
connect.held_write_confirmation_refused |
409 | A confirmação expirou ou a escrita mudou desde a prévia. Abra a prévia de novo. | — |
connect.held_write_connector_paused |
409 | O conector está pausado, então a escrita não saiu. Ela ficou confirmada e sai sozinha quando o conector for ligado de novo. | — |
connect.held_write_decided |
409 | Essa escrita já foi decidida: ela já saiu, está saindo ou foi trocada por uma mais nova. | — |
connect.held_write_not_found |
404 | Não encontramos essa escrita guardada neste conector. | — |
connect.held_write_outdated |
409 | A versão publicada não escreve mais nesse sistema. A próxima execução guarda uma nova escrita para confirmar. | A próxima execução guarda uma nova primeira escrita para confirmar. |
connect.held_write_relay_failed |
502 | A escrita não saiu agora e continua confirmada. Ela sai sozinha em instantes, ou confirme de novo. | — |
connect.held_write_send_uncertain |
502 | A escrita falhou no meio do caminho e pode ter chegado ao outro sistema. Ela não será repetida: confira no outro sistema. | A escrita pode ter chegado. Confira no outro sistema antes de qualquer nova tentativa; ela não é repetida. |
IA de construção
Seção intitulada “IA de construção”| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
connect.ai_month_cap_reached |
429 | A IA do Connect chegou ao limite de uso da loja neste mês. Ela volta quando o limite renovar. | O teto mensal de IA da loja foi atingido. Copiloto e construção voltam quando o mês virar; conectores ligados continuam rodando. |
connect.build_turn_in_progress |
409 | A IA ainda está respondendo a mensagem anterior. Espere ela terminar. | Espere a IA terminar a resposta anterior. |
connect.build_unavailable |
503 | A IA de construção ainda não está disponível neste ambiente. | — |
connect.fix_run_not_found |
404 | Não encontramos esta execução neste conector. | — |
connect.run_still_running |
409 | Esta execução ainda está rodando. Peça a correção quando ela terminar. | Peça a correção quando a execução terminar. |
Copiloto
Seção intitulada “Copiloto”| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
connect.handoff_not_found |
404 | Esta proposta não está mais disponível. Peça de novo ao Copiloto. | — |
Documentação
Seção intitulada “Documentação”| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
connect.doc_not_found |
404 | Essa página da documentação do Connect não existe. | — |
| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
connect.mcp_confirmation_invalid |
409 | Essa confirmação não vale mais: ela expirou, já foi usada ou é de outra pessoa. Peça a prévia de novo e confirme com o token novo. | Chame preview_operation de novo e confirme com o token novo, dentro do prazo e uma vez só. |
connect.mcp_run_not_found |
404 | Não encontramos essa execução neste conector. | — |
connect.mcp_run_now_not_enabled |
409 | Ligue o conector antes de mandar rodar agora. | — |
connect.mcp_scope_missing |
403 | Este aplicativo não tem a permissão {scope}. A pessoa precisa conectar de novo marcando essa permissão. | Desconecte o aplicativo e conecte de novo marcando a permissão que falta na tela de consentimento. |
Login de aplicativos (CLI e MCP)
Seção intitulada “Login de aplicativos (CLI e MCP)”| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
connect.oauth_insufficient_scope |
403 | Este aplicativo não tem a permissão necessária ({required}). Conecte de novo marcando essa permissão. | Conecte de novo marcando a permissão pedida na tela de consentimento. |
connect.oauth_invalid_token |
401 | O acesso deste aplicativo expirou ou foi revogado. Conecte de novo. | Na CLI, rode zoppy-connect login; no cliente MCP, conecte o servidor de novo. |
connect.oauth_no_scope |
422 | Escolha ao menos uma permissão para conectar o aplicativo. | — |
connect.oauth_request_not_found |
404 | Esse pedido de conexão não existe mais ou já foi decidido. Peça a conexão de novo no aplicativo. | — |
| Código | Status | Mensagem | O que fazer |
|---|---|---|---|
core.missing_context |
500 | Erro inesperado. Tente novamente em instantes. | — |
core.missing_tenant_context |
500 | Erro inesperado. Tente novamente em instantes. | — |
core.search_timeout |
503 | A busca demorou demais. Use palavras mais específicas e tente de novo. | — |
core.too_many_attempts |
429 | Muitas tentativas. Aguarde alguns minutos e tente novamente. | — |
internal_error |
— | Erro inesperado. Se persistir, envie o código abaixo para o suporte. | — |
llm.budget_exceeded |
429 | O assistente atingiu o limite de uso deste mês. Ele volta a responder no mês que vem. | — |
llm.invalid_request |
422 | O assistente não está configurado corretamente. Avise o suporte com o código abaixo. | — |
llm.task_budget_exceeded |
429 | Esta leitura ficou grande demais para o limite da tarefa. Avise o suporte com o código abaixo. | — |
llm.unavailable |
503 | O assistente está fora do ar agora. Tente novamente em instantes. | — |
llm.unknown_task |
500 | Erro inesperado. Tente novamente em instantes. | — |
mail.delivery_failed |
— | Não conseguimos enviar o e-mail agora. Tente novamente em instantes. | — |
mail.unknown_template |
— | Erro inesperado. Tente novamente em instantes. | — |
prompt.task_not_registered |
— | Erro inesperado. Tente novamente em instantes. | — |
storage.artifact_expired |
410 | Este arquivo passou do prazo de retenção e não está mais disponível. | — |
storage.file_not_found |
404 | Arquivo não encontrado. | — |
storage.invalid_key |
— | Nome de arquivo inválido. | — |
storage.operation_failed |
502 | Não conseguimos acessar o arquivo agora. Tente novamente em instantes. | — |
validation_failed |
— | Confira os campos destacados e tente novamente. | — |
webhook_ingress.route_retired |
— | Esta rota de webhook só existe no ambiente local. Em nuvem, o webhook entra pelo endpoint do API Gateway. | — |