Support codes

# Support codes

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

A support code is the short, stable code shown on a receipt that names where an event stopped — authentication, validation, workflow readiness, or the Shopify Flow handoff. Use it to decide what FlowRelay can prove and what the next safe action is, and quote it instead of pasting private request details.

## Read the code before acting
A FlowRelay support 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.


## Canonical support-code catalog
This table is contract-checked against the current public Shopify Flow support-code set. Private future-edition codes are intentionally excluded from the public Shopify Flow documentation.


- Code: FLR_ENDPOINT_UNKNOWN; Stage: Readiness; Meaning: The sender URL does not map to an active endpoint; Retry class: Configuration fix; Next safe action: Correct the endpoint URL, then send a fresh event from the sender; Related guide: /setup/endpoints/
- Code: FLR_ENDPOINT_DELETED; Stage: Readiness; Meaning: The sender URL belongs to a deleted endpoint; Retry class: Configuration fix; Next safe action: Create a replacement endpoint, update the sender, then send a fresh event; Related guide: /setup/endpoints/
- Code: FLR_AUTH_HEADER_MISSING; Stage: Authentication; Meaning: The request omitted the endpoint's configured authentication header; Retry class: Configuration fix; Next safe action: Correct the sender header name, then send a fresh event; Related guide: /setup/authentication/
- Code: FLR_AUTH_FAILED; Stage: Authentication; Meaning: The configured static secret or HMAC signature did not verify; Retry class: Configuration fix; Next safe action: Correct the sender secret, mode, or exact-body signing input, then send a fresh event; Related guide: /setup/authentication/
- Code: FLR_PAYLOAD_INVALID_JSON; Stage: Validation; Meaning: The request body was not valid JSON; Retry class: Sender retry; Next safe action: Correct the JSON and send a fresh event from the sender; Related guide: /setup/event-types-and-payloads/
- Code: FLR_PAYLOAD_TOO_LARGE; Stage: Validation; Meaning: The request body exceeded the 256 KB v1 limit; Retry class: Sender retry; Next safe action: Reduce the JSON payload and send a fresh event from the sender; Related guide: /setup/event-types-and-payloads/
- Code: FLR_MAPPING_REQUIRED_VALUE_MISSING; Stage: Validation; Meaning: A configured path did not resolve to a required value; Retry class: Configuration fix; Next safe action: Correct the sender payload or endpoint mapping, then preview replay only if the event is retained; Related guide: /setup/trigger-variants-and-event-mapping/
- Code: FLR_MAPPING_INVALID_RESOURCE_ID; Stage: Validation; Meaning: A native or related-resource identifier could not be normalized safely; Retry class: Configuration fix; Next safe action: Correct the trigger variant or identifier path, then preview replay if the event is retained; Related guide: /setup/trigger-variants-and-event-mapping/
- Code: FLR_NO_ENABLED_WORKFLOW; Stage: Readiness; Meaning: No matching enabled Shopify Flow workflow was known for the trigger variant; Retry class: Replay candidate; Next safe action: Enable the matching workflow, verify Source and Event type conditions, then preview replay; Related guide: /setup/shopify-flow-trigger/
- Code: FLR_DUPLICATE_SUPPRESSED; Stage: Validation; Meaning: The same external event ID was already accepted for this endpoint inside the dedupe window; Retry class: Manual review; Next safe action: Open the linked first receipt; replay only when a second Shopify Flow run is intentional; Related guide: /recover/duplicates-and-idempotency/
- Code: FLR_FLOW_HANDOFF_FAILED; Stage: Handoff; Meaning: Shopify Flow rejected the normalized trigger handoff; Retry class: Replay candidate; Next safe action: Correct the trigger or mapped fields, inspect diagnostics, then preview replay if safe; Related guide: /recover/replay/
- Code: FLR_SHOPIFY_SESSION_UNAVAILABLE; Stage: Handoff; Meaning: FlowRelay could not access the Shopify Admin context needed for handoff; Retry class: Configuration fix; Next safe action: Reopen FlowRelay from Shopify Admin; contact support before replay if the problem repeats; Related guide: /recover/support-signals/
- Code: FLR_SHOPIFY_SCOPE_MISSING; Stage: Handoff; Meaning: The native-reference trigger lacks its required optional Shopify scope; Retry class: Configuration fix; Next safe action: Have an authorized admin grant the optional scope, then preview replay; Related guide: /setup/permissions-and-data-access/
- Code: FLR_SHOPIFY_HANDOFF_THROTTLED; Stage: Handoff; Meaning: Shopify asked FlowRelay to slow the handoff; Retry class: Wait/backoff; Next safe action: Wait for FlowRelay's paced retry; do not replay while processing remains active; Related guide: /recover/retries-replay-and-resend/
- Code: FLR_SHOPIFY_HANDOFF_UNAVAILABLE; Stage: Handoff; Meaning: Shopify was temporarily unavailable during handoff; Retry class: Wait/backoff; Next safe action: Wait for FlowRelay's retry and check the terminal receipt before considering replay; Related guide: /recover/retries-replay-and-resend/
- Code: FLR_SHOPIFY_HANDOFF_AMBIGUOUS; Stage: Handoff; Meaning: FlowRelay could not confirm whether Shopify received the handoff; Retry class: Manual review; Next safe action: Check Shopify Flow activity and diagnostics before any replay; a second handoff may duplicate downstream actions; Related guide: /recover/replay/
- Code: FLR_PLATFORM_CONTEXT_MISMATCH; Stage: Authorization; Meaning: The grant and requested FlowRelay resource belong to different platform contexts; Retry class: Non-retryable; Next safe action: Use a grant and FlowRelay surface for the same platform context as the resource; Related guide: /agent-access/availability-and-refusals/
- Code: FLR_PLAN_LIMIT_REACHED; Stage: Capacity; Meaning: The current plan or paid-plan grace no longer permits the requested intake or action; Retry class: Wait/backoff; Next safe action: Wait for reset or use the human billing handoff; agents must not approve charges; Related guide: /operate/usage-limits/
- Code: FLR_REPLAY_NOT_AVAILABLE; Stage: Replay; Meaning: The receipt has no retained material that FlowRelay can replay; Retry class: Sender retry; Next safe action: Send a fresh event from the source system instead of reconstructing private payload data; Related guide: /recover/replay/
- Code: FLR_DIAGNOSTICS_UNAUTHORIZED; Stage: Diagnostics; Meaning: The current actor is not allowed to create a diagnostics share for this store; Retry class: Non-retryable; Next safe action: Ask an authorized store admin or scoped operator to create the share; Related guide: /recover/diagnostics/
- Code: FLR_DIAGNOSTICS_FAILED; Stage: Diagnostics; Meaning: FlowRelay could not create or retrieve the redacted diagnostics snapshot; Retry class: Wait/backoff; Next safe action: Retry once, then contact support with the visible redacted summary if it still fails; Related guide: /recover/diagnostics/

## Escalate safely
Escalate with the support code, receipt ID, and diagnostics share. Do not share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs.


## Decision guide
Start with the receipt, then choose the lowest-risk recovery path.
- When: You are investigating one event
  Then: Open its receipt and find the literal FlowRelay support code.
- When: You have the support code
  Then: Read the failure fact FlowRelay can prove from that code.
- When: The code names a next safe action
  Then: Follow that action before replaying or changing endpoint configuration.
- When: A partner or support team needs evidence
  Then: Create and approve a redacted diagnostics share.
- When: The code requires authority outside the current grant
  Then: Stop and escalate to an authorized human.

## 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 share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.