# Erros de requisição externa, webhook e planilha

> Os códigos HTTP que outro sistema devolve à requisição externa e os avisos dos webhooks e do Google Sheets, com o que cada um quer dizer e o que fazer.

Endereço: https://help.nextags.com.br/tutoriais/erros/erros-de-requisicao-externa/
Tipo: Referência · Avançado

Atualizado em: 25/10/2026

Quando um fluxo chama outro sistema pela ação **External API Request**, a resposta traz um código HTTP: de 200 a 299 é sucesso; de 400 em diante, erro. Você vê o código no **Testar Agora** da ação. No quadro, a ação tem as saídas **Sucesso** e **Falhado**, e as falhas dos fluxos ficam no **Registro de Erros**.

![Aba Testar Agora com o resultado do teste: código do estado 200, corpo da resposta e os cabeçalhos e o corpo da solicitação.](https://help.nextags.com.br/_img/fluxos-acoes/requisicao-testar.webp)
*O resultado do Testar Agora.*

1. **Código do estado**: o código HTTP que o outro sistema devolveu.
2. **Corpo da resposta**: o que ele devolveu. Muitas APIs explicam o erro aqui.

## Os códigos HTTP

| Código | O que quer dizer | O que fazer | Veja |
|---|---|---|---|
| 400 | O outro sistema não entendeu o pedido (*Bad Request*). | Confira o **Corpo** e os campos obrigatórios na documentação da API. | [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) |
| 401 | Falta a autenticação ou ela não vale (*Unauthorized*). | Confira a chave ou o token nos **Cabeçalhos**, como em `Authorization`. | [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) |
| 403 | O sistema entendeu, mas recusou o acesso (*Forbidden*). | Confira se a chave tem permissão para essa operação. | [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) |
| 404 | O endereço não existe (*Not Found*). | Confira o **Request URL** e as variáveis dentro dele. | [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) |
| 405 | O método não vale nesse endereço (*Method Not Allowed*). | Troque o **Request Type**: GET, POST, PUT, PATCH ou DELETE. | [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) |
| 408 | O outro sistema cansou de esperar o pedido (*Request Timeout*). | Tente de novo. | [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) |
| 415 | O formato do corpo não é aceito (*Unsupported Media Type*). | Use o formato que a API pede: **JSON** ou **Form-encoded**. | [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) |
| 422 | O pedido está no formato certo, mas com valores que a API não aceita (*Unprocessable Content*). | Confira os valores, como telefone, e-mail e datas. | [Personalizar com o nome e outros campos](https://help.nextags.com.br/tutoriais/fluxos/variaveis-nas-mensagens/) |
| 429 | Pedidos demais em pouco tempo (*Too Many Requests*). | Espere e diminua a frequência. O limite está na documentação da API. | [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) |
| 500 | Erro dentro do outro sistema (*Internal Server Error*). | O problema está do outro lado: avise quem cuida da API. | [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) |
| 502, 503 e 504 | O outro sistema está fora do ar, sobrecarregado ou demorou para responder (*Bad Gateway*, *Service Unavailable* e *Gateway Timeout*). | Tente mais tarde. Ligue a saída **Falhado** a uma mensagem de reserva ou à equipe. | [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) |

Fonte: [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#name-status-codes) e [RFC 6585](https://www.rfc-editor.org/rfc/rfc6585#section-4), as normas que definem os códigos HTTP, consultadas em 25/10/2026.

## Avisos da requisição externa

| Aviso | O que quer dizer | O que fazer | Veja |
|---|---|---|---|
| *O JSON no corpo da solicitação não é válido* | O corpo em JSON tem um erro de escrita. | Confira as aspas duplas, as vírgulas e as chaves. Os campos entram entre aspas, como `"{{full_name}}"`. | [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) |
| *Não foi possível concluir esta operação.*, no **Testar Agora** | O teste não chegou ao fim. | Confira o **Request URL** e tente de novo. | [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) |
| O campo do **Mapeamento de resposta** ficou vazio | O caminho (JSONPath) não bate com a resposta. | Abra o **Testar Agora**, veja o **Corpo da resposta** e corrija o caminho. | [Obter dados de JSON](https://help.nextags.com.br/tutoriais/fluxos/dados-de-json/) |

## Webhooks de entrada

Os avisos do editor do webhook de entrada estão em inglês.

| Aviso | O que quer dizer | O que fazer | Veja |
|---|---|---|---|
| *Start the path with $.* | O caminho precisa começar com `$`. | Escreva como `$.email`, ou escolha o valor pela lupa. | [Webhooks de entrada](https://help.nextags.com.br/tutoriais/ferramentas/webhook-de-entrada/) |
| *Use .key, ["key"], or [0]. Filters and wildcards are not supported.* | O caminho usa um formato que o editor não aceita. | Use só `.chave`, `["chave"]` e `[0]`, sem filtros nem curingas. | [Webhooks de entrada](https://help.nextags.com.br/tutoriais/ferramentas/webhook-de-entrada/) |
| *Select a value rather than an object or array.* | O caminho aponta para um grupo de dados, não para um valor. | Escolha um valor dentro do grupo. | [Webhooks de entrada](https://help.nextags.com.br/tutoriais/ferramentas/webhook-de-entrada/) |
| *No value found in sample data.* | O exemplo colado não tem valor nesse caminho. Pode ser um campo que nem sempre vem. | Confira o caminho, ou cole um exemplo com o campo preenchido. | [Webhooks de entrada](https://help.nextags.com.br/tutoriais/ferramentas/webhook-de-entrada/) |
| *Configure an email or phone number to identify the contact.* | Falta o caminho do telefone ou do e-mail. | Preencha em **Find or create contact**. | [Webhooks de entrada](https://help.nextags.com.br/tutoriais/ferramentas/webhook-de-entrada/) |
| *Configure at least one field mapping.* | Falta ligar pelo menos um dado a um campo. | Adicione em **Save incoming data**. | [Webhooks de entrada](https://help.nextags.com.br/tutoriais/ferramentas/webhook-de-entrada/) |
| *Select an available flow to trigger after the data is saved.* | Falta escolher o fluxo. | Escolha em **Enviar Fluxo**. | [Webhooks de entrada](https://help.nextags.com.br/tutoriais/ferramentas/webhook-de-entrada/) |
| O outro sistema manda, mas nada acontece | O webhook está desligado, o link é de outro webhook ou o JSON não traz o telefone nem o e-mail. | Siga o passo a passo da pergunta frequente. | [Meu webhook de entrada não recebe os dados](https://help.nextags.com.br/perguntas/integracoes/webhook-nao-recebe/) |

## Webhooks de saída

| Aviso | O que quer dizer | O que fazer | Veja |
|---|---|---|---|
| *The URL must start with https* | O endereço precisa ser seguro, com `https://`. | Troque o endereço em **Notificar este URL** por um com `https://`. | [Webhooks de saída](https://help.nextags.com.br/tutoriais/ferramentas/webhooks-de-saida/) |
| *Add at least 1 action*, ao salvar | Apesar do texto, o problema é o endereço: ele não é válido. | Confira o endereço em **Notificar este URL**. | [Webhooks de saída](https://help.nextags.com.br/tutoriais/ferramentas/webhooks-de-saida/) |
| O seu sistema não recebe os avisos | O webhook está desligado, o evento é outro ou o endereço não responde. | Confira a chave **Estado** na lista, o evento e o endereço. | [Webhooks de saída](https://help.nextags.com.br/tutoriais/ferramentas/webhooks-de-saida/) |

## Google Sheets

| Aviso | O que quer dizer | O que fazer | Veja |
|---|---|---|---|
| *Vá para Configurações > Integrações e conecte sua Conta do Google* | A conta do Google não está conectada. | Conecte em **Configurações** › **Integrações**. | [Planilhas do Google](https://help.nextags.com.br/tutoriais/configuracoes/planilhas-google/) |
| *Sua WorkSheet não contém uma linha como cabeçalho.* | A primeira linha da folha precisa ter os títulos das colunas. | Escreva os títulos, como ID, nome, e-mail e telefone, e abra a ação de novo. | [Google Sheets no fluxo](https://help.nextags.com.br/tutoriais/fluxos/google-sheets-no-fluxo/) |
| *Recrie esta ação do Planilhas Google* | A planilha salva na ação não está mais na lista da conta. | Escolha de novo a planilha e a folha e salve. | [Google Sheets no fluxo](https://help.nextags.com.br/tutoriais/fluxos/google-sheets-no-fluxo/) |
| *Por favor, preencha todos os campos obrigatórios* | Falta escolher a **Planilha** ou a **Folha de cálculo**. | Escolha as duas antes de salvar. | [Google Sheets no fluxo](https://help.nextags.com.br/tutoriais/fluxos/google-sheets-no-fluxo/) |
| A ação sai pela saída **Falhado** | O fluxo não conseguiu usar a planilha. | Confira se a planilha e a folha ainda existem e se a conta do Google conectada tem acesso a elas. | [Planilhas do Google](https://help.nextags.com.br/tutoriais/configuracoes/planilhas-google/) |

> **Para quem desenvolve:**
> O guia [Requisição externa: o fluxo chama o seu sistema](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/) mostra como preparar o seu endpoint, e [Segurança, testes e novas tentativas](https://docs.nextags.com.br/webhooks/seguranca-e-testes/) explica como testar os webhooks.