Error Codes - Circle Docs

Circle Mint surfaces errors in two shapes: synchronous responses to API calls, and asynchronous status transitions on resources. The tables below catalog every code, organized by product. When an endpoint returns a generic code: -1 with a message of Something went wrong, treat it as the transient fallback and retry with backoff.

Error response shape

Every synchronous error returns an HTTP status code plus a JSON body with a numeric code and a human-readable message. Validation errors include an extended errors[] array with one entry per offending field.

{
  "code": 2,
  "message": "Invalid entity."
}

{
  "code": 2,
  "message": "Invalid entity.",
  "errors": [
    {
      "error": "min_value",
      "message": "Must be at least 1.",
      "location": "amount",
      "invalidValue": "0",
      "constraints": { "min": 1 }
    }
  ]
}

Each entry in errors[] carries an error name that you can branch on programmatically:

Name	Meaning
`required`	Field is missing.
`min_value`	Value is below the allowed minimum.
`max_value`	Value exceeds the allowed maximum.
`length_outside_bounds`	String length is outside the allowed range.
`pattern_mismatch`	Value didn’t match the required regular expression pattern.
`date_not_in_past`	Date must be in the past.
`date_not_in_future`	Date must be in the future.
`number_format`	Value isn’t a valid number for the field.
`value_must_be_true`	The boolean field must be `true`.
`value_must_be_false`	The boolean field must be `false`.
`not_required`	Field was provided but is disallowed.
`invalid_value`	Value isn’t in the allowed set for this field.

Synchronous and asynchronous errors

Circle Mint surfaces errors in two distinct shapes depending on when the problem is detected.

Kind	Where it surfaces
Synchronous	Returned inline in the HTTP response with a status code (`400`, `401`, `403`, `404`, `409`, `429`, or `500`) and a JSON body containing `code` and `message`.
Asynchronous	Surfaced on a resource after it reaches a terminal `failed` (or denied) status. The resource carries a string `errorCode` and, for risk-driven denials, an optional `riskEvaluation` object.

Recommended treatment

Use these categories to decide how your integration should respond to a given error.

Category	Signal	Action
Malformed request	4xx response with a validation `errors[]` array.	Fix the request and retry with the same `idempotencyKey`.
State conflict	409 response, or a `code` indicating an existing or conflicting resource.	Re-fetch the resource state and decide whether to retry, update, or skip.
Insufficient funds	`insufficient_funds` on a payout or transfer, or `INSUFFICIENT_BALANCE` on a credit draw.	Top up the source wallet (or wait for a credit repayment) and retry.
Compliance or risk denial	Asynchronous `errorCode` paired with `riskEvaluation.decision = denied`.	Review the originator and beneficiary information, then resubmit with a new `idempotencyKey`.
Transient or network	5xx response, timeout, or generic `code: -1`.	Retry with exponential backoff. If the error persists, contact Circle.

Common errors

These codes can appear on any endpoint.

Code	Meaning	HTTP	Treatment
`-1`	Something went wrong.	500	Transient
`1`	Malformed authorization header.	401	Malformed
`2`	Invalid entity.	400	Malformed
`3`	Forbidden.	403	State conflict

Core API errors

These codes cover the core money-movement endpoints: payments, payouts, transfers, and blockchain address management.

Code	Meaning	Treatment
`1077`	Payment amount must be greater than zero.	Malformed
`1078`	Payment currency not supported.	Malformed
`1083`	Idempotency key already bound to another request—retry with a different value.	State conflict
`1084`	This item cannot be canceled.	State conflict
`1085`	This item cannot be refunded.	State conflict
`1086`	This payment was already canceled.	State conflict
`1087`	Total amount to be refunded exceeds the original payment amount.	Malformed
`1088`	Invalid source account specified in a payout or transfer request.	Malformed
`1089`	The source account could not be found.	Malformed
`1093`	Source account has insufficient funds for the payout or transfer amount.	Insufficient funds
`1096`	Encryption key ID could not be found; an encryption key ID is required for encrypted data.	Malformed
`1097`	Cannot cancel or refund a failed payment.	State conflict
`1100`	Invalid country format.	Malformed
`1101`	Invalid country format—provide a valid ISO 3166-1 alpha-2 country code.	Malformed
`1106`	Invalid district format—must be a 2-character value.	Malformed
`1107`	Payout limit exceeded.	State conflict
`1108`	Country not supported for customer.	Malformed
`1112`	Country or district error on a request payload.	Malformed
`2003`	The recipient blockchain address is already associated with the account.	State conflict
`2004`	The blockchain address is not a verified withdrawal address.	State conflict
`2005`	The blockchain address belongs to an unsupported blockchain.	Malformed
`2006`	The wallet type specified when creating an end-user wallet is not supported.	Malformed
`2007`	A transfer from the provided source to the provided destination is not supported.	Malformed
`2009`	Unsupported transfer configuration.	Malformed
`2020`	Unsupported transfer request.	Malformed
`5001`	Payout doesn’t exist—verify the payout ID.	Malformed
`5002`	Payout amount must be greater than zero.	Malformed
`5003`	Inactive destination address. Addresses may require a 24-hour wait after creation before use.	State conflict
`5004`	The destination address for this payout could not be found.	Malformed
`5005`	The source wallet for this payout could not be found.	Malformed
`5006`	The source wallet has insufficient funds for this payout.	Insufficient funds
`5007`	Currency not supported for this operation.	Malformed
`5011`	Invalid destination address.	Malformed
`5012`	Cannot search for both crypto and fiat payouts at the same time.	Malformed
`5013`	Source wallet ID must be a number for payouts search.	Malformed
`5014`	The blockchain address is not valid for the corresponding blockchain.	Malformed
`5015`	The destination blockchain doesn’t match the currency used.	Malformed
`5017`	Destination address or blockchain configuration error on a payout request.	Malformed

Stablecoin Payins errors

Most Stablecoin Payins asynchronous failures surface via the payments webhook and the paymentIntent lifecycle rather than through discrete error codes. The synchronous codes below cover checkout-session validation.

Code	Meaning	Treatment
`1143`	Checkout session not found—the supplied session ID doesn’t exist.	Malformed
`1144`	Checkout session is already in a completed state and cannot be extended.	State conflict

For asynchronous failure events on payment intents and payments, see Webhook Notifications.

Stablecoin Payouts errors

Stablecoin Payouts errors have two sources. Synchronous validation covers Travel Rule fields and Address Book entity validation. After submission, the payout entity itself can transition to failed with an errorCode that describes why.

Synchronous validation

For full Travel Rule context, see Travel Rule Compliance.

Code	Meaning	Treatment
`5020`	`purposeOfTransfer` field is missing or invalid on a `CIRCLE_SG`-booked crypto payout.	Malformed
`2024`	Address Book identity is missing for this entity.	Malformed
`2025`	Address Book ownership is missing for this entity.	Malformed
`2026`	Address Book VASP ID is missing for this entity.	Malformed
`2027`	Address Book ownership type is invalid for this entity.	Malformed
`2028`	Address Book custody type is invalid for this entity.	Malformed
`2029`	Address Book custody is missing for this entity.	Malformed
`2030`	Address Book VASP ID is invalid for this entity.	Malformed
`2031`	Address Book identity type is invalid—must be `individual` or `business`.	Malformed
`2032`	Address Book identity first name is missing for an individual identity.	Malformed
`2033`	Address Book identity last name is missing for an individual identity.	Malformed
`2034`	Address Book identity business name is missing for a business identity.	Malformed
`2035`	Address Book VASP ID is not allowed—VASP ID must be omitted for self-hosted custody.	Malformed
`2036`	Identity is not allowed in Address Book `PATCH` requests.	Malformed
`2037`	Ownership is not allowed in Address Book `PATCH` requests.	Malformed

Asynchronous entity errors

`errorCode`	Meaning
`insufficient_funds`	Source wallet doesn’t have enough USDC for the payout.
`transaction_denied`	Payout was denied by Circle Risk Service—see `riskEvaluation` for the reason.
`transaction_failed`	Payout failed due to an unknown reason.
`transaction_returned`	Payout was returned by the receiving network.
`fiat_account_limit_exceeded`	The fiat account limit was exceeded.

When riskEvaluation.reason is 3220, the denial is a Travel Rule violation. Review your originator identities, beneficiary identity, VASP ID, and purposeOfTransfer, then resubmit with a new idempotencyKey. See Travel Rule Compliance.

Credit errors

The Credit API’s draw, fee, and repayment endpoints surface validation failures via a top-level validationErrors array on the credit line. When validationErrors is non-empty, draw and repayment endpoints return HTTP 400 until the listed conditions clear.

Value	Meaning	Treatment
`INSUFFICIENT_BALANCE`	The credit line’s Circle Mint wallet balance is below `minBalance`, blocking new draws.	State conflict
`PENDING_FEES`	An unpaid fee is blocking new draws.	State conflict
`OVERDUE_TRANSFERS`	At least one disbursed transfer is past its due date.	State conflict

Calling POST /v1/credit/cryptoRepayment against a Settlement Advance credit line returns HTTP 400—crypto repayment is only supported on Line of Credit lines. See the Credit API concept for product differences.

Institutional Distribution errors

These responses surface when you create or manage external entities through the Institutional API.

HTTP	Meaning	Treatment
`400`	Missing or invalid fields on external entity creation.	Malformed
`401`	The API key doesn’t have the Institutional Distribution permission.	State conflict: contact Circle to enable the entitlement.
`409`	An external entity with the supplied `businessUniqueIdentifier` and `identifierIssuingCountryCode` already exists. Re-fetch via `GET /v1/externalEntities`.	State conflict

Custody balance errors

These codes apply to daily user balance reporting for custody accounts.

Code	Meaning	Treatment
`500000`	Unsupported currency for reporting daily user balance—must be USDC or EURC.	Malformed
`500001`	Custody balance `asOfDate` is too far from today’s date.	Malformed
`500002`	Custody balance cannot be less than zero.	Malformed
`500003`	Local custody balance can’t be greater than total custody balance.	Malformed
`500004`	Idempotency key can’t be reused across different requests.	State conflict
`500005`	A custody balance report already exists for the provided date and currency. Contact customer care for edits.	State conflict

Transfer entity errors

These errorCode values appear on a transfer resource after it transitions to failed.

`errorCode`	Meaning	Treatment
`transfer_failed`	Transfer could not be completed.	Transient: investigate `riskEvaluation` and network conditions.
`transfer_denied`	Transfer was denied by Circle Risk Service.	Compliance: review and resubmit with a new `idempotencyKey`.
`blockchain_error`	Onchain failure prevented the transfer from settling.	Transient: retry once network is healthy.
`insufficient_funds`	Source wallet doesn’t have enough USDC for the transfer.	Insufficient funds

​Error response shape

​Synchronous and asynchronous errors

​Recommended treatment

​Common errors

​Core API errors

​Stablecoin Payins errors

​Stablecoin Payouts errors

​Synchronous validation

​Asynchronous entity errors

​Credit errors

​Institutional Distribution errors

​Custody balance errors

​Transfer entity errors

Error response shape

Synchronous and asynchronous errors

Recommended treatment

Common errors

Core API errors

Stablecoin Payins errors

Stablecoin Payouts errors

Synchronous validation

Asynchronous entity errors

Credit errors

Institutional Distribution errors

Custody balance errors

Transfer entity errors