ERROR_MAP

This map normalizes Wagyu API errors and order status signals into user-safe messages and recommended actions. Use it in the BFF and UI layers.

HTTP Error Codes (Wagyu)

Code	Meaning	User Message	Action
400	Invalid request parameters	"We couldn't process that request. Please check the details and try again."	Validate inputs client-side and in BFF.
401	Missing or invalid API key	"Service configuration error. Please try again later."	Alert ops; verify API key and fee config.
403	Verification failed (destination address mismatch)	"Verification failed. Please confirm the destination address."	Prompt user for correct destination address.
404	Order not found	"We couldn't find that order. Please check the ID."	Ask for order ID or destination address.
429	Rate limit exceeded	"We're receiving too many requests. Please wait and try again."	Backoff and retry with jitter.
500	Internal server error	"A temporary error occurred. Please try again."	Retry with backoff; alert if sustained.

Order Status to UX Guidance

Status	User Message	Action
awaiting_deposit	"Waiting for your deposit."	Show deposit address and amount; remind exact amount.
deposit_detected	"Deposit detected. Waiting for confirmations."	Show confirmations progress.
deposit_confirmed	"Deposit confirmed. Processing swap."	Show estimated time remaining.
executing_swap	"Swap in progress."	Show live status.
completed	"Swap completed."	Display tx hash and received amount.
refunding	"Refund in progress."	Explain refund path and timeline.
refunded	"Funds refunded."	Show refund transaction hash.
failed	"Swap failed."	Show error message and support CTA.
expired	"Order expired (no deposit received in time)."	Offer to create a new order.

Notes:

• Orders expire if no deposit is received within the allowed window (documented as 2 hours).

• When a swap cannot be completed, it transitions to refunding and then refunded with refundTxHash, and errorMessage explains the reason. citeturn1view0