FireHorse Pay/developersDashboard
Build

Find the next action

Start with the HTTP response, then follow routing, provider initiation, terminal state and webhook delivery in order.

400 / 401: request or signature rejected#

Check required fields and JSON, API key, clock in seconds, a fresh nonce, lowercase hex HMAC, exact raw body and the signed /api/v1 path without proxy prefix or query. A reused nonce can reject a valid logical retry.

409: duplicate or state conflict#

For a duplicate create, recover the existing transaction using your stored ID or reference. Do not generate another idempotency key to bypass a duplicate response. For refund/void conflicts, inspect current state and supported transitions.

No eligible provider / unavailable method#

Check merchant and provider regions, operational binding, onboarding approval, mode, currency, payment method, country and amount limits. FX can change the amount/currency used for routing. Connections identifies the responsible role for missing setup.

201 CREATED or PROCESSING is still pending#

A worker initiates the provider call asynchronously. A slow provider can leave the initial response without redirectUrl. Retrieve the transaction with backoff and check its trace; never fulfil on CREATED or PROCESSING.

A missing provider callback, missing merchant webhook and a rejected payment are different failures. Inspect the stage that actually has evidence.

422 FX_RATE_UNAVAILABLE / 429 rate limit#

For FX_RATE_UNAVAILABLE, review destination currency and a valid configured rate. The rejected request did not create a transaction. For a rate limit, back off and preserve your logical idempotency key, using a fresh nonce for every HTTP attempt.

Prepare a safe support request#

Include timestamp with timezone, HTTP status, transaction UUID/numeric ID, merchant reference, environment and the failing stage. Remove API keys, signatures, capability URLs, personal data and raw sensitive payloads. Use the authenticated dashboard for scoped trace evidence.

Search documentation