FAQ and troubleshooting

This page collects the situations that operators meet often in an integration. It grows with the questions that come from support traffic.

I sent the same request again. Why did the balance not change?

A request with the same Idempotency-Key and the same body returns the first response unchanged, and it applies nothing a second time. This is a replay, not an error. For balance syncs, we replay the stored response for 90 days. For position opens, we replay it with no time limit.

I get 422 idempotency_key_reused.

You sent the same key with a different body. Nothing was applied, and the first request stays valid. Generate a new Idempotency-Key for a new intent. Use a key again only when you retry the same request.

I got 409 would_overdraw. Must I retry?

No. This code says that the debit movement would take the virtual balance of the user below zero. In this case, our view and your view have drifted apart. We record the request as rejected and we flag it for reconciliation. If you repeat the same request blindly, the drift does not close. First compare the balance-sync history of the user, send the missing sync, and then send the operation again with a new Idempotency-Key.

I got 404 unknown_user.

The user is not registered yet. Register the user with PUT /v1/users/{external_user_id}, then retry with the same key and the same body. We do not record this error, so the key is not spent.

I get 429 rate_limited.

You went over the request limit of your tenant. Wait for the time that the Retry-After header of the response gives, then retry with the same key and the same body. This retry is safe because of idempotency. If you retry at once and repeatedly, the limit stays active for longer. The tiers and limits are on the Rate limits page.

I got 503 sync_paused or another *_paused code.

We paused that path for a short time. We did not record the request. Retry later with the same key and the same body.

The webhook signature does not match.

The most common cause is that the signature was computed over JSON that was parsed and written again. Compute the signature over the raw body bytes. Then check these points:

• Does the value that you compare include the sha256= prefix?
• Do you compare the hex output in lowercase?
• Is the webhook_secret that you use the last value that we gave you? When the secret changes, the old secret becomes invalid at once.

I will open a support ticket for an error. What must I send?

Send the request_id and source values from the error envelope. Do not send personal data of your end users. You can open the ticket from the tenant portal, or with POST /v1/support-tickets using a key that has the write:tickets scope.