> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/troubleshooting/when-an-event-fails.md).

# What happens when an event fails

*Article · Collection: Troubleshooting*

Sometimes an event you send cannot be processed. The data did not match what an attribute expects, a required field was missing, or a reference pointed somewhere invalid. Flapjax never drops these quietly. This article explains what happens next and how to fix it.

## Two kinds of failure

**1. Flapjax rejects the request immediately.**

You call the API with malformed or invalid data and get an error straight back. The response is a `4xx` with a message naming the problem: bad JSON, a validation failure, a duplicate ID, a missing permission. Nothing gets stored. This is the friendliest kind of failure. You know instantly, and you can correct and resend.

**2. Flapjax accepts the request, then hits a problem processing it.**

Some data passes the door and fails deeper in, such as a streamed event that fails validation later. Flapjax records it as a **failed event** for you to review. Short-lived problems get a few automatic retries first. Only after those retries does Flapjax record the failure.

## Where to find failed events

Failed events live in **Settings → Monitors**. The list shows:

* when it failed,
* what it was, meaning a person or a record, and which stack,
* the operation: create, update or delete,
* the kind of error,
* the error message.

Click any row for the detail view. It shows the full error and the exact payload you sent, so you can see what came in.

Common error kinds:

| Error kind                                  | What it means                                                                                              |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **permanent**                               | The request could never succeed as sent. Bad format, unknown operation, or a permission and scope problem. |
| **validation**                              | The data did not meet an attribute's rules.                                                                |
| **duplicate** / **duplicate\_external\_id** | Something with that ID exists already.                                                                     |
| **transient\_exhausted**                    | A temporary problem outlasted every automatic retry.                                                       |

## How to fix them

The Failed Events monitor is for inspection. It tells you what went wrong. To recover, correct the data and resend it through the API.

There is no retry button, and that is deliberate. The fix nearly always means changing the data first, or switching to an upsert so a resend is safe. After a successful resend, Flapjax stores the person or record normally and your automations fire as usual.

Three practical tips:

* **Use upsert** for creates you might resend. It updates an existing record instead of failing on a duplicate.
* **Check the payload** in the detail view against your attribute definitions: types, required, unique.
* **Watch reference errors.** A relationship pointing at something that should not be auto-created means you need the target to exist first.

## What you will not see here

The Failed Events monitor covers problems with getting your data in. It does not show internal processing hiccups inside automations. The Flapjax platform team handles and monitors those.

Where such a problem touches you, it surfaces elsewhere. An automation that hits trouble may **pause itself** and show a reason on its canvas. A message that could not be delivered shows a `failed` status on the Communications page.

## Quick recap

Bad requests get rejected instantly with a clear error. Accepted events that cannot be processed get retried, then recorded in **Settings → Monitors** for you to inspect. Fix the data and resend. Upsert makes resending safe.