Pular para o conteúdo principal

Solução de problemas (FAQ)

Organizado como 'sintoma → causa → correção'. Falhas de conexão, falhas de autenticação, texto ilegível e variáveis não resolvidas são as quatro grandes categorias.

Falhas de conexão / envio​

SintomaCausa provávelCorreção
'Sem endereço base' reportadoGrupo sem ambiente vinculado, ou o ambiente não tem o Pre-URL desse protocoloVincule um ambiente, adicione o Pre-URL do protocolo
WS/gRPC/MQTT não conectaScheme do Pre-URL errado (o protocolo é classificado pelo scheme)ws usa ws/wss, grpc usa grpc/grpcs, mqtt usa mqtt/mqtts
TCP/UDP não conectaHost e porta invertidosHost recebe o endereço, porta é campo separado
Erros de TLSScheme criptografado mas certificado não configuradoImporte um certificado de cliente, ou desative a verificação TLS conforme necessário
Conexão longa cai de repenteRetomada automaticamente quando ociosaReconecte antes de usar; feche sessões antigas prontamente ao depurar em lote (cota tem limite)

Autenticação (401 / 403)​

SintomaCausaCorreção
401 mesmo com tokenO script de pré-envio não rodou (execução de scripts desativada)Confirme que 'executar scripts' está ativado
{{authToken}} permanece literal (não substituído){{}} não lê tokens armazenados em runtimeUse um script de pré-envio com sdk.env.get para injetar o cabeçalho (veja recipes, cenário 1)
Requisição seguinte não obtém o token após loginAs duas requisições estão em grupos / ambientes diferentesColoque-as no mesmo grupo vinculado ao mesmo ambiente (variáveis de runtime têm escopo por ambiente)

Texto ilegível / codificação​

SintomaCausaCorreção
Chinês ilegível na respostaServidor retorna não-UTF-8 (ex.: GBK)Decodifique com o charset correspondente; reproduza via /charset/gbk
Descriptografia retorna string Error: ...Ciphertext inválido/vazio, ou key/iv difere da criptografia (falhas de $crypto só retornam string de erro, nunca lançam/interrompem)Mantenha key e iv idênticos na criptografia/descriptografia; verifique se a string de retorno começa com Error: (chinês em texto puro faz round-trip bem, verificado)
Script reporta Script aborted requestUma exceção JS não capturada no script (comum: valores de cabeçalho não-ASCII em headers.set, ou acesso a propriedade de undefined)Envolva chamadas arriscadas em try/catch; coloque conteúdo UTF-8 em body/params de query e mantenha valores de cabeçalho ASCII
Resultado base64 estranho em scriptsPassou um Uint8Array/bytes para $codec/sdk.utils (virado String() em "97,98,99" antes de codificar)Sempre passe strings; tanto $codec.base64Encode/Decode quanto sdk.utils.base64Encode/Decode são string↔string com UTF-8 — escolha um

Scripts não têm efeito​

SintomaCausaCorreção
Script de pré-envio mudou o body mas o tráfego não mostraNão é reescrita por 'atribuição'request.body = new string (atribuição substitui o body inteiro)
Reescrita pós-resposta invisívelComo reescreverresponse.body = new string; a UI/visão de resultado mostra o novo conteúdo após reescrever
Script reportado como 'sem ponto de entrada, ignorado'Nome da função erradoDeve se chamar onRequest / onResponse
Scripts não leem os valores uns dos outrosDesconhecimento do mecanismo de compartilhamentoScripts na mesma cadeia compartilham globalThis — passe valores via globalThis.xxx
AES 'falha na criptografia' em scriptsForma de argumento errada$crypto.encryptAES recebe strings posicionais, não um objeto {text,key,iv}
Script falha com require: 未找到库 [...]A chave da biblioteca está errada, ou uma biblioteca de scripts do usuário foi renomeada/excluídaCopie o require statement do gerenciador de bibliotecas (forma identifier sobrevive a renomeações); chaves integradas são @libs/base64 / @libs/hex; require em comentários é ignorado e nunca empacotado

Cola de resolução de variáveis​

  • {{name}}: resolve apenas variáveis de configuração de ambiente / variáveis por envio; não consegue ler valores armazenados em runtime por scripts.
  • Ler variáveis dentro de scripts: as três camadas são legíveis — use isso para passar tokens entre requisições.
  • Para tornar valores extraídos também utilizáveis por {{}}: ative a configuração 'gravar extração de volta no ambiente'.

Detalhes: concepts, o sistema de variáveis.

Ainda travado?​

  • Primeiro faça o 'caso mínimo funcional' rodar com /echo (HTTP) ou /ws/echo (WS), depois adicione auth/scripts passo a passo.
  • Depure um passo por vez: a requisição consegue sair (não conecta → verifique Pre-URL/host/porta) → os scripts executam (execução de scripts ativada?) → as variáveis resolvem (qual camada)?
  • Erros relacionados a scripts podem ser cruzados com a Referência da API de scripts.