Troubleshooting

Audience: Anyone debugging a 4xx or 5xx from the Gateway. Reading time: ~7 minutes, but treat it as a lookup reference, not a linear read. Prerequisites: None. You'll learn: The two response envelopes (StandardError + ProblemDetails), the URN-typed error catalogue for /flow/* routes, the common pitfalls, and where to get help.

Errors from the Overledger Gateway use one of two envelopes depending on the route.

11.1 Error envelopes

StandardError, non-Flow routes

Returned with Content-Type: application/json from every route outside /flow/* (users, contracts, networks, nodes, providers, stakes, deposits, RPC).

{
  "timestamp": 1709737845000,
  "status": 400,
  "error": "Bad request",
  "message": "Validation failed",
  "path": "/users/me/deposits"
}

ProblemDetails (RFC 7807), /flow/* routes

Returned with Content-Type: application/problem+json from every Flow App route (sessions, registry, queries, subscriptions, events).

{
  "type": "urn:fusion:error:bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "appId is required",
  "retryable": false,
  "instance": "/flow/sessions/abc123"
}

11.2 Flow-route error types

These are the URN values you'll see in the type field on /flow/* responses:

retryable: true is a hint, not a guarantee, back off before retrying and limit retry depth.

11.3 Common non-Flow status codes

The error and message fields on StandardError are intended to be self-describing. The most common combinations:

11.4 Common pitfalls

"Every request returns 401."

The most common cause: the Authorization header is malformed. It must be exactly Authorization: Bearer <api-key> (one space, no quotes, no leading/trailing whitespace). For RPC endpoints, you can also pass the API key in the URL path as /rpc/<api-key> instead.

"Submit returns Idempotency-Key required."

POST /flow/sessions/{sessionId}/steps/{stepId} requires an Idempotency-Key header (any string, 1–256 chars). It is cached per session, reuse the same key when retrying a failed submission; use a fresh key for each genuine submission.

"Submit returns the wrong response with Idempotency-Key."

You reused a key that already produced a response on this session. The cached response is returned without re-executing. Use a fresh key for the new attempt.

"Adding a node fails with a domain validation error."

POST /nodes accepts URLs for public nodes only from the approved provider domains (alchemy.com, infura.io, quiknode.pro, chainstack.com, getblock.io, blockdaemon.com, ankr.com, drpc.live) with the API key embedded in the URL path. See chapter 5.2.

"My token never landed on the Fusion Rollup after a deposit."

1. Check GET /users/me/deposits, what does the deposit's status say?
2. If the status hasn't progressed for >30 min, look up the underlying L1 transaction on a block explorer. Did it succeed?
3. If the L1 tx succeeded but the Fusion Rollup hasn't picked it up, contact [email protected] with the L1 tx hash and your deposit record's identifier. Most likely you called an incorrect function on the deposit. We recommend using Quant's token interchange or Quant's flow applications in order to make a valid deposit.

"Flow App render returns 502 with bad-gateway."

If the response's detail mentions a content-filter rule, the offending string came from the Flow App's StepSpec (not from your request). The fix is in the Flow App. If the detail doesn't mention content filtering, the downstream Flow App's /renderStep returned an error, check the app's /health and its own logs.

"RPC method works locally but returns 403 through the Gateway."

You're calling a blocked admin method (personal_*, admin_*, txpool_*, …). The Gateway never forwards these. Use public alternatives, or run your own node and route around the Gateway for admin-only flows.

"Withdrawal finalize keeps failing."

Optimistic-rollup withdrawals have a dispute window, see chapter 8.7. Confirm:

1. The Fusion Rollup state root containing your withdrawal has been posted to the destination DLT network.
2. The dispute window has elapsed.
3. No challenge has been opened against that state root.

11.5 Where to get help

• General Support, [email protected]. Include the instance (for /flow/* errors) or the path and rough timestamp (for StandardError).
• Flow Application Support, utilise the Flow Feedback application in Quant Connect.