---
title: "Run reached the failed state."
method: POST
path: "run.failed"
---

# Run reached the failed state.

`POST run.failed` (webhook)

Sent once a run terminates unsuccessfully. The payload carries the same buyer-safe `reason` as GET /runs/{id}. Delivery is at-least-once. Each attempt has a 5 second timeout; a 5xx, 408, 425, 429, connection error, or timeout is retried with exponential backoff (up to 6 attempts over roughly 9 hours, honouring a longer Retry-After). Any other 4xx or a redirect is treated as a permanent rejection and is not retried. Because an event can therefore arrive more than once, deduplicate on the edgaze-delivery-id header, which is stable across retries. Endpoints are delivered in parallel and ordering is not guaranteed. An endpoint whose deliveries fail 15 times consecutively is paused until it is re-enabled in the developer console. Return 2xx as soon as you have persisted the payload, and do the real work asynchronously.

## Headers

- `edgaze-signature` string, required
- `edgaze-webhook-id` string, uuid, required
- `edgaze-delivery-id` string, uuid
- `edgaze-attempt` integer, required
- `edgaze-event` string, required

## Payload

- WebhookRunEventPayload: Body posted to a webhook endpoint when a run reaches a terminal state.
  - `id` string, uuid, required: Unique event id, safe to dedupe on.
  - `type` 'run.completed' | 'run.failed' | 'run.cancelled', required
  - `createdAt` string, date-time, required
  - `data` object, required
    - `runId` string, uuid, required
    - `workflowId` string, uuid, nullable, required
    - `status` 'pending' | 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled', required: Canonical run status exposed by the public API.
    - `outcome` 'completed' | 'completed_with_issues', nullable: Set when `status` is `completed`, null otherwise. `completed`: every step finished. `completed_with_issues`: the run returned its outputs but some steps failed; it is charged for the completed steps' compute only, without the creator's price.
    - `displayedChargeUsd` number, nullable

## Acknowledgement `200`

Acknowledge receipt. Any 2xx settles the delivery. A 5xx, 408, 425, 429, timeout, or connection error is retried with backoff; any other 4xx or a redirect permanently fails the delivery.

---

[API](https://skmtc.dev/edgaze/apis/edgaze-api.md) · [All operations](https://skmtc.dev/edgaze/apis/edgaze-api/llms.txt) · [OpenAPI document](https://skmtc.dev/edgaze/apis/edgaze-api/revisions/cfc6436d2f90?raw)