> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aciona.me/llms.txt
> Use this file to discover all available pages before exploring further.

# O webhook retornou erro

> O que cada código de resposta significa e como corrigir.

O endpoint de ingestão responde com códigos específicos. Cada um aponta para uma causa diferente.

## 401 — token inválido

O header `X-Aciona-Token` está ausente, com valor errado ou pertence a outra fonte.

<Steps>
  <Step title="Confirme o nome do header">
    Precisa ser exatamente `X-Aciona-Token`. Alguns painéis adicionam prefixos automáticos ao nome do header — verifique o valor final enviado.
  </Step>

  <Step title="Confirme que o token é o daquela fonte">
    Cada fonte tem seu próprio token. Um token válido para outra fonte gera `401`.
  </Step>

  <Step title="Verifique se o token foi rotacionado">
    A rotação invalida o token anterior imediatamente. Atualize a ferramenta externa.
  </Step>
</Steps>

<Note>
  Nada é persistido em uma requisição com `401`. Não há registro do alerta para consultar depois.
</Note>

## 403 — fonte inativa

A fonte existe e o token está correto, mas a fonte está **desativada**. Reative em **Fontes de alerta**.

## 404 — fonte não encontrada

O identificador na URL não corresponde a nenhuma fonte. Causas comuns:

* A fonte foi excluída.
* A URL foi copiada parcialmente, ou com espaço/quebra de linha.
* Falta um trecho do caminho: a URL correta é `https://ingress.aciona.me/webhooks/<idDaFonte>`.

## 400 — payload inválido

O corpo não é um JSON válido, ou faltam campos obrigatórios do tipo de fonte.

<AccordionGroup>
  <Accordion title="Corpo não é JSON" icon="braces">
    Confirme o header `Content-Type: application/json` e que o corpo é JSON bem formado. Templates com aspas não escapadas quebram o JSON — valide a saída renderizada do template, não o template.
  </Accordion>

  <Accordion title="Zabbix" icon="activity">
    `triggerId` e `name` são obrigatórios. Confira as macros `{EVENT.TRIGGERID}` e `{EVENT.NAME}` nos parâmetros da media type.
  </Accordion>

  <Accordion title="CloudWatch" icon="cloud">
    `alarmName` e `alarmArn` são obrigatórios no payload canônico. Verifique se a Lambda está recebendo a mensagem SNS esperada.
  </Accordion>

  <Accordion title="Grafana e Prometheus" icon="chart-line">
    O payload precisa conter o array `alerts`. Um POST manual de teste sem esse array é recusado por uma fonte desses tipos.
  </Accordion>
</AccordionGroup>

## 413 — payload muito grande

O corpo excedeu o limite (por padrão, 1 MB). Reduza os campos enviados no template — payloads do Datadog e do New Relic podem ficar enormes quando incluem snapshots ou o objeto de detalhes completo.

## 429 — muitas requisições

A origem está enviando alertas acima do ritmo aceito. Agrupe alertas na própria ferramenta (`group_by` e `group_interval` no Alertmanager, agrupamento no Grafana) em vez de enviar um POST por série.

## 5xx — erro do lado do aciona.me

Raro. A maioria das ferramentas retenta automaticamente em `5xx`. Se persistir, entre em contato com o suporte informando o horário e o identificador da fonte.

<Card title="Todos os códigos de resposta" icon="list" href="/pt-br/referencia/respostas-do-webhook" horizontal />
