Charges Error Handling
For error response format and general handling, see Key concepts.
Parse internalStatus from every non-2xx response and map it to an action. Do not rely on HTTP status alone, and do not retry 409s — they reflect a state conflict that a retry will not resolve.
POST /crypto/v2/charge-locks
POST /crypto/v2/charge-locksinternalStatus | HTTP | Description | Action |
|---|---|---|---|
INVALID_PARAMS | 400 | Missing or malformed body fields | Fix request payload |
INVALID_COIN | 400 | entryAsset or exitAsset not supported | Use a supported asset — see Coverage |
INVALID_COIN_COUNTRY | 400 | Asset not enabled for the user's country | Use the user's local currency or a crypto asset |
PRICE_PATH_NF | 404 | No price route between entryAsset and exitAsset | Choose a supported corridor — see Coverage |
POST /crypto/v2/synthetics/charge
POST /crypto/v2/synthetics/chargeinternalStatus | HTTP | Description | Action |
|---|---|---|---|
INVALID_PARAMS | 400 | Missing or malformed body fields | Fix request payload |
WITHDRAW_DESTINATION | 400 | destination.address is not valid for the given network | Validate the destination before submitting |
INVALID_NETWORK | 400 | The network does not support the exitAsset | Check valid asset/network combinations in Coverage |
CHARGE_LOCK_NF | 404 | chargeCode not found, already used, or expired | Create a new charge lock and retry |
SYNTHETIC_EXISTS | 409 | externalId already consumed by another synthetic | Idempotency: fetch the existing synthetic instead of creating |
After creation
Once the charge exists, outcomes surface through the synthetic lifecycle rather than the creation response: if the payer never pays within the lock window, the synthetic moves to CANCELLED. See Charge lifecycle.
Related pages
- Coverage — valid asset / network combinations
- Charge lifecycle — synthetic statuses and the confirmation webhook
Updated 27 days ago
Did this page help you?