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
| Sintoma | Causa provável | Correção |
|---|---|---|
| 'Sem endereço base' reportado | Grupo sem ambiente vinculado, ou o ambiente não tem o Pre-URL desse protocolo | Vincule um ambiente, adicione o Pre-URL do protocolo |
| WS/gRPC/MQTT não conecta | Scheme 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 conecta | Host e porta invertidos | Host recebe o endereço, porta é campo separado |
| Erros de TLS | Scheme criptografado mas certificado não configurado | Importe um certificado de cliente, ou desative a verificação TLS conforme necessário |
| Conexão longa cai de repente | Retomada automaticamente quando ociosa | Reconecte antes de usar; feche sessões antigas prontamente ao depurar em lote (cota tem limite) |
Autenticação (401 / 403)
| Sintoma | Causa | Correção |
|---|---|---|
| 401 mesmo com token | O 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 runtime | Use 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 login | As duas requisições estão em grupos / ambientes diferentes | Coloque-as no mesmo grupo vinculado ao mesmo ambiente (variáveis de runtime têm escopo por ambiente) |
Texto ilegível / codificação
| Sintoma | Causa | Correção |
|---|---|---|
| Chinês ilegível na resposta | Servidor 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 request | Uma 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 scripts | Passou 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
| Sintoma | Causa | Correção |
|---|---|---|
| Script de pré-envio mudou o body mas o tráfego não mostra | Não é reescrita por 'atribuição' | request.body = new string (atribuição substitui o body inteiro) |
| Reescrita pós-resposta invisível | Como reescrever | response.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 errado | Deve se chamar onRequest / onResponse |
| Scripts não leem os valores uns dos outros | Desconhecimento do mecanismo de compartilhamento | Scripts na mesma cadeia compartilham globalThis — passe valores via globalThis.xxx |
| AES 'falha na criptografia' em scripts | Forma 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ída | Copie 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.