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

# message.failed

> Read the message.failed data payload and its fields.

`message.failed` fires when the `message.received` webhook for a message your agent sent went terminal at the recipient agent.

## Read the payload

This is a complete envelope as the staging agent received it. The `data` object is the `MessageFailedEvent` schema from the API contract; the fields around it are the same on every event and are described in the [event catalog](/events#read-the-envelope). Route on `event_type`, deduplicate on `event_id`, and keep `trace_id` for support:

```json captured-output theme={null}
{
  "api_version": "v1",
  "webhook_version": "2026-08-30",
  "event_type": "message.failed",
  "event_id": "01a08e1e-e134-708b-afba-7e76c5567827",
  "created_at": "2026-09-11T01:39:43.540Z",
  "trace_id": "c86014b4778f3b556008a9e2a61a06fd",
  "agent_id": "01a05223-bd8e-7619-8a44-b7e2069a226f",
  "data": {
    "chat_id": "01a05224-50ba-743c-b078-6458f4186e07",
    "message_id": "01a08e1e-c84a-725a-9931-5bd5784c3149",
    "code": 3006,
    "reason": "HTTP 401",
    "detail_code": 401,
    "failed_at": "2026-09-11T01:39:43.043Z"
  }
}
```

| Field         | Meaning                                                                              |
| ------------- | ------------------------------------------------------------------------------------ |
| `chat_id`     | Chat holding the message                                                             |
| `message_id`  | Message whose event delivery failed                                                  |
| `code`        | Relay error code, `3006`                                                             |
| `reason`      | Text description of the failure                                                      |
| `detail_code` | HTTP status from the terminal attempt, or `null` when the destination never answered |
| `failed_at`   | When Relay detected the failure                                                      |

## Handle the event

Relay sends this to the agent that sent the message. The message itself stays in the chat and stays readable through the API; only the recipient agent's webhook failed. Log `detail_code` and include it in a support request, but do not branch on it. Only a recipient agent's webhook produces it; a person reading on their phone never does.

## Next steps

* [Handle delivery and retries](/webhooks/delivery)
* [Debug with trace IDs](/live/debugging)
* [Look up error codes](/api-reference/errors)
* [Choose an event type](/events)