# Error codes

Canonical: https://docs.flowrelay.app/recover/error-codes/
Markdown: https://docs.flowrelay.app/recover/error-codes.md

Use stable FlowRelay error codes to decide what the product can prove and what the next safe action is.

## Read the code before acting
A FlowRelay error code explains the boundary where the event stopped. Use it to choose whether the sender, endpoint, Shopify Flow setup, FlowRelay processing, or support should own the next step.


## Common recovery paths
These examples describe FlowRelay-native recovery decisions rather than generic webhook behavior.


- Code family: Authentication failed; What it means: FlowRelay could not trust the request.; Next action: Fix sender auth and ask the sender to send a fresh event.
- Code family: Validation or mapping failed; What it means: The request was missing required JSON, event type, or identifier data.; Next action: Fix the endpoint mapping or sender payload, then use a sender resend.
- Code family: No workflow; What it means: FlowRelay accepted the event but no matching enabled Shopify Flow trigger was ready.; Next action: Enable the trigger, then preview FlowRelay replay if the event is retained.
- Code family: Handoff failed; What it means: FlowRelay could not complete the handoff to Shopify Flow.; Next action: Check replay availability and share diagnostics if support needs evidence.
- Code family: Retention expired; What it means: FlowRelay no longer has replayable event material.; Next action: Ask the sender to send a fresh event rather than reconstructing private data.

## Escalate safely
Escalate with the stable code, receipt ID, and diagnostics package. Do not include raw bodies, full headers, secrets, tokens, sessions, database URLs, customer data, or copied private incidents.


## Decision guide
Start with the receipt, then choose the lowest-risk recovery path.
1. Open the receipt and find the stable FlowRelay error code.
2. Read what FlowRelay can prove from that code, such as authentication failure, validation failure, missing workflow readiness, or handoff failure.
3. Follow the next safe action for the code before replaying or changing endpoint configuration.
4. Use diagnostics when a partner or support team needs redacted evidence.
5. Escalate when the code indicates an action outside the current operator or agent grant.

## Handoff Boundary
Delivered means FlowRelay handed the trigger to Shopify Flow. It does not mean downstream Shopify Flow branches, app calls, fulfillment changes, emails, or later systems completed.

## Related
- [Retries, replay, and resend](https://docs.flowrelay.app/recover/retries-replay-and-resend.md)
- [Replay an event](https://docs.flowrelay.app/recover/replay.md)
- [Share diagnostics](https://docs.flowrelay.app/recover/diagnostics.md)

## Safety Boundary
Do not include raw payloads, endpoint secrets, auth headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.