Error codes

HTTP status codes and numeric error codes returned by Managed Payments endpoints, with causes and remediation steps

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.