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

internalStatusHTTPDescriptionAction
INVALID_PARAMS400Missing or malformed body fieldsFix request payload
INVALID_COIN400entryAsset or exitAsset not supportedUse a supported asset — see Coverage
INVALID_COIN_COUNTRY400Asset not enabled for the user's countryUse the user's local currency or a crypto asset
PRICE_PATH_NF404No price route between entryAsset and exitAssetChoose a supported corridor — see Coverage

POST /crypto/v2/synthetics/charge

internalStatusHTTPDescriptionAction
INVALID_PARAMS400Missing or malformed body fieldsFix request payload
WITHDRAW_DESTINATION400destination.address is not valid for the given networkValidate the destination before submitting
INVALID_NETWORK400The network does not support the exitAssetCheck valid asset/network combinations in Coverage
CHARGE_LOCK_NF404chargeCode not found, already used, or expiredCreate a new charge lock and retry
SYNTHETIC_EXISTS409externalId already consumed by another syntheticIdempotency: 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



Did this page help you?