Error codes

Errors from Managed Payments endpoints use a flat response and the following endpoint-specific numeric codes. For general errors returned by any Circle API, see API errors.

Error response shape

Managed Payments endpoints return errors as a flat object:

{
  "code": 1177,
  "message": "The purposeOfTransfer field is missing or invalid",
  "errors": []
}

Common error codes

Status code	Error code	Description
`500`	`-1`	Circle couldn’t process the request. Retry later. If it fails again, contact Circle support with the `errId`.
`401`	`1`	The `Authorization` header is missing or malformed. Pass the API key as a `Bearer` token.
`400`	`2`	A request field is missing or has the wrong type. Check `message` for the field name.
`403`	`3`	The API key can’t use this resource, or your entity doesn’t support it.
`401`	`4`	The API key is invalid, expired, or inactive. Check the key.
`429`	`5`	Too many requests. Wait, then retry.

Create a payment intent

Codes returned by POST /v1/paymentIntents.

Status code	Error code	Description
`400`	`1127`	Send one blockchain payment method. The value can’t be `null` or contain more than one method.
`400`	`1128`	Set `expiresOn` to a time in the future.
`400`	`1130`	The currency and blockchain pair isn’t supported. Use a supported pair or confirm support with Circle.
`400`	`1131`	The intent and settlement currency pair isn’t supported. Use a supported pair.
`400`	`1132`	The amount is `0`, less than `0`, or has too many decimal places. Send a valid amount.
`400`	`1177`	`purposeOfTransfer` is missing or invalid. Circle LLC (United States) and Circle Singapore (`CIRCLE_SG`) require it. See payment reason codes.
`400`	`1069`	The merchant doesn’t own the `merchantWalletId`, or the wallet wasn’t found. Check the ID.
`409`	`1083`	The idempotency key is bound to another request. Fetch that result, or use a new key for a new request.

Refund a payment intent

Codes returned by POST /v1/paymentIntents/{paymentIntentId}/refund.

Status code	Error code	Description
`400`	`1130`	The refund currency and blockchain pair isn’t supported. Use a supported pair.
`400`	`1137`	The intent has no completed crypto payment, or the intent failed. It can’t be refunded.
`400`	`1138`	Use the source currency from the first payment or settlement.
`400`	`1141`	The refund currency must match the first payment.
`400`	`1142`	The amount is more than the balance that can be refunded. Reduce it.
`400`	`1145`	The 30-day refund window has passed. Handle the refund outside this API.
`400`	`1146`	A crypto payment is still pending. Wait for it to finish, then retry.
`400`	`1165`	Set one destination: a raw `address` and `chain`, or an `addressBookId`.
`400`	`1166`	Use an address book entry owned by the merchant’s legal entity. Circle Singapore (`CIRCLE_SG`) requires this.
`400`	`1167`	The address book entry isn’t active. Wait for approval, then retry.
`400`	`1168`	The crypto payment can’t be refunded in its current state. Check the state before you retry.
`400`	`1169`	The total refund is more than the crypto payment. Reduce the amount.
`400`	`1170`	The payment doesn’t belong to this intent. Use the correct payment.
`400`	`1178`	The refund amount must be greater than `0`.
`404`	`1126`	The payment intent wasn’t found. Check `paymentIntentId`.
`404`	`1164`	The address book entry wasn’t found. Check `addressBookId`.

Circle Singapore (CIRCLE_SG) doesn’t support a raw refund destination. Use an addressBookId or set useOriginalSender: true.

Address book recipients

Codes returned when creating or updating an address book recipient.

Status code	Error code	Description
`400`	`2024`	Circle Singapore (`CIRCLE_SG`) recipients require `identity`.
`400`	`2025`	Circle Singapore (`CIRCLE_SG`) recipients require `ownership`.
`400`	`2026`	A hosted-custody recipient requires `ownership.custody.vaspId`.
`400`	`2027`	`ownership.type` isn’t supported. Circle Singapore (`CIRCLE_SG`) recipients must use `third_party`.
`400`	`2028`	`ownership.custody.type` isn’t supported for this entity.
`400`	`2029`	Set `ownership.custody`.
`400`	`2030`	`ownership.custody.vaspId` isn’t a known VASP.
`400`	`2031`	`identity.type` must be `individual` or `business`.
`400`	`2032`	An individual recipient requires a first name in `identity.individual`.
`400`	`2033`	An individual recipient requires a last name in `identity.individual`.
`400`	`2034`	A business recipient requires a business name in `identity.business`.
`400`	`2035`	A self-hosted recipient must not set `ownership.custody.vaspId`.
`400`	`2038`	A self-hosted Circle Singapore (`CIRCLE_SG`) recipient requires `metadata.email`. Its `ownership.custody.type` is `self_hosted`.
`400`	`2048`	A self-hosted individual recipient requires `identity.individual`.
`400`	`2049`	A self-hosted business recipient requires `identity.business`.

Stablecoin payouts

Codes returned by stablecoin payout endpoints.

Status code	Error code	Description
`400`	`5000`	The travel rule `identity.type` must be `individual` or `business`.
`400`	`5002`	The payout amount must be greater than `0`.
`400`	`5003`	The destination address is inactive.
`400`	`5004`	The destination address wasn’t found.
`400`	`5005`	The source wallet wasn’t found.
`400`	`5006`	The source wallet lacks funds. Check that its wire has settled.
`400`	`5007`	The currency isn’t supported for this operation.
`400`	`5011`	The destination address is invalid. If you just added it, wait up to 24 hours before using it.
`400`	`5015`	The destination blockchain is invalid for the currency.
`400`	`5020`	Circle LLC (United States) and Circle Singapore (`CIRCLE_SG`) payouts require a valid `purposeOfTransfer`. See payment reason codes.
`400`	`5021`	The destination address isn’t associated with the source sub-wallet.

Create a withdrawal

Codes returned when POST /v1/accounts/withdrawals sends fiat to a linked bank account.

Status code	Error code	Description
`400`	`5002`	The payout amount must be greater than `0`.
`400`	`5006`	The source wallet lacks funds. Add funds or wait for settlement, then retry.
`400`	`5007`	The currency isn’t supported. Use a supported currency.
`400`	`5016`	The fiat account can’t use this transfer type. Check what the account supports.
`400`	`5017`	The transfer limit was reached. Reduce the amount or wait for the limit to reset.
`400`	`5019`	The payout limit was reached. Reduce the amount or wait for the limit to reset.
`400`	`1112`	The fiat account wasn’t found. Check that it is registered.
`400`	`1100`	The fiat account type is invalid for payouts.
`400`	`1089`	The source account wasn’t found. Verify the source account ID.

Asynchronous withdrawal outcomes

A valid POST /v1/accounts/withdrawals call returns 201 at once with data.status: "pending". Get the final result from the payouts webhook or GET /v1/accounts/withdrawals/{id}. Store trackingRef to match the wire on your bank statement.

`data.status`	`data.errorCode`	Description
`pending`	(omitted)	The withdrawal was accepted and is processing. Wait for the webhook.
`complete`	(omitted)	USD was sent to the bank. Record `trackingRef` for reconciliation.
`failed`	`insufficient_funds`	The account ran out of funds after acceptance. Retry once funds are replenished.
`failed`	`transaction_denied`	A policy or risk check denied the wire. Contact Circle support. Don’t retry on your own.
`failed`	`transaction_failed`	Circle or the bank couldn’t process the wire. Retry once. If it fails again, contact support with the withdrawal ID.
`failed`	`transaction_returned`	The bank sent the wire back. Fix the bank details, register the account again, and retry.
`failed`	`bank_transaction_error`	The bank reported an error. Contact your bank and Circle support.
`failed`	`fiat_account_limit_exceeded`	The bank account reached its inbound limit. Ask the bank to raise it, then retry.
`failed`	`invalid_bank_account_number`	The bank account number is wrong. Register the account again with the right number.
`failed`	`invalid_ach_rtn`	The ACH routing number is invalid. Circle Singapore (`CIRCLE_SG`) accounts use wires only. Use the right SWIFT/BIC.
`failed`	`invalid_wire_rtn`	The SWIFT/BIC is invalid. Register the account again with the right value.
`failed`	`vendor_inactive`	A bank used by Circle is down for now. Retry in 5 to 10 minutes. Contact support if it still fails.
`failed`	`payout_canceled`	The withdrawal was canceled before it settled. Submit a new withdrawal if you still need it.
`failed`	`invalid_travel_rule_identity`	The travel rule identity failed validation. Circle Singapore (`CIRCLE_SG`) requires it. Correct the details and retry.
`failed`	`intermediary_bank_required`	The wire needs an intermediary bank. Add intermediary bank details to the account, then retry.

Wire accounts

Status code	Error code	Description
`400`	`1106`	Set `billingDetails.district` for addresses in the United States or Canada. Use the state or province code.

Idempotency

An idempotency key stays bound to its record and doesn’t expire. The same body returns the first record. A new body returns 409 with code 1083. Use a new UUID for each new request.

Fiat payouts

Managed Payments

Stablecoin payments

Error response shape

Common error codes

Create a payment intent

Refund a payment intent

Address book recipients

Stablecoin payouts

Create a withdrawal

Asynchronous withdrawal outcomes

Wire accounts

Idempotency

​Error response shape

​Common error codes

​Create a payment intent

​Refund a payment intent

​Address book recipients

​Stablecoin payouts

​Create a withdrawal

​Asynchronous withdrawal outcomes

​Wire accounts

​Idempotency

Error response shape

Common error codes

Create a payment intent

Refund a payment intent

Address book recipients

Stablecoin payouts

Create a withdrawal

Asynchronous withdrawal outcomes

Wire accounts

Idempotency