> ## 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.

# The webhook returned an error

> What each response code means and how to fix it.

The ingestion endpoint answers with specific codes. Each points at a different cause.

## 401 — invalid token

The `X-Aciona-Token` header is missing, has the wrong value, or belongs to another source.

<Steps>
  <Step title="Check the header name">
    It must be exactly `X-Aciona-Token`. Some UIs prepend a prefix to custom header names — verify the value that actually goes out.
  </Step>

  <Step title="Check the token belongs to that source">
    Each source has its own token. A token that is valid for another source produces `401`.
  </Step>

  <Step title="Check whether the token was rotated">
    Rotation invalidates the previous token immediately. Update the external tool.
  </Step>
</Steps>

<Note>
  Nothing is persisted on a `401` request. There is no alert record to inspect afterwards.
</Note>

## 403 — inactive source

The source exists and the token is right, but the source is **deactivated**. Re-activate it under **Alert sources**.

## 404 — source not found

The identifier in the URL matches no source. Common causes:

* The source was deleted.
* The URL was copied partially, or with a space or line break.
* Part of the path is missing: the correct URL is `https://ingress.aciona.me/webhooks/<alertSourceId>`.

## 400 — invalid payload

The body is not valid JSON, or required fields for that source type are missing.

<AccordionGroup>
  <Accordion title="Body is not JSON" icon="braces">
    Confirm the `Content-Type: application/json` header and that the body is well-formed JSON. Templates with unescaped quotes break the JSON — validate the rendered output, not the template.
  </Accordion>

  <Accordion title="Zabbix" icon="activity">
    `triggerId` and `name` are required. Check the `{EVENT.TRIGGERID}` and `{EVENT.NAME}` macros in the media type parameters.
  </Accordion>

  <Accordion title="CloudWatch" icon="cloud">
    `alarmName` and `alarmArn` are required in the canonical payload. Check that the Lambda is receiving the expected SNS message.
  </Accordion>

  <Accordion title="Grafana and Prometheus" icon="chart-line">
    The payload must contain the `alerts` array. A manual test POST without it is rejected by a source of those types.
  </Accordion>
</AccordionGroup>

## 413 — payload too large

The body exceeded the limit (1 MB by default). Trim the fields sent in the template — Datadog and New Relic payloads can get enormous when they include snapshots or the full details object.

## 429 — too many requests

The origin is sending alerts faster than allowed. Group alerts in the tool itself (`group_by` and `group_interval` in Alertmanager, grouping in Grafana) instead of sending one POST per series.

## 5xx — error on the aciona.me side

Rare. Most tools retry automatically on `5xx`. If it persists, contact support with the time and the source identifier.

<Card title="All response codes" icon="list" horizontal href="/en/reference/webhook-responses" />
