Errors

Use error.code to decide how to handle a failure and keep request_id for troubleshooting. The sections below describe the response format, retry behavior, rate limits, and individual codes.

Error categories and customer actions

These categories group errors by the action a customer can take. They are documentation categories; the response does not yet include a category or retryable field. error.type describes the existing exception family and is not a substitute for error.code.

Category	Representative codes	Customer action
Authentication and access	`UNAUTHORIZED`, `ACCESS_DENIED`, `KYC_NOT_APPROVED`, `APPROVAL_NOT_AUTHORIZED`	Correct credentials, permissions or verification before trying again.
Invalid request	`VALIDATION_ERROR`, `INVALID_FIELD_VALUE`, `MISSING_REQUIRED_FIELD`, `CURRENCY_MISMATCH`, `REQUEST_TOO_LARGE`	Correct the named fields; repeating the same request will not help.
Resource state and conflicts	`RESOURCE_NOT_FOUND`, `DUPLICATE_RESOURCE`, `IDEMPOTENCY_CONFLICT`, `VIRTUAL_ACCOUNT_INACTIVE`, `APPROVAL_NOT_PENDING`	Read the resource and resolve the missing, duplicate or incompatible state.
Availability and eligibility	`CURRENCY_NOT_ENABLED`, `WALLET_UNSUPPORTED_COMBINATION`, `FX_PAIR_NOT_ENABLED`, `PLATFORM_FEE_NOT_ENABLED`	Select an enabled option or contact support about enabling it.
Funds, amounts and limits	`INSUFFICIENT_FUNDS`, `CREDIT_LIMIT_EXCEEDED`, `AMOUNT_EXCEEDS_MAXIMUM`, `LIMIT_EXCEEDED`	Fund the balance, adjust the amount, reuse an existing resource or discuss the limit with support.
Temporary service failures	`RATE_LIMIT_EXCEEDED`, `CREDIT_CHECK_UNAVAILABLE`, `FX_PRICING_UNAVAILABLE`, `GATEWAY_ERROR`	Follow the retry guidance below; check the operation’s state before retrying a write.
Operation failures requiring review	`PAYOUT_FAILED`, `AGREEMENT_ACTION_FAILED`, `CONFIGURATION_ERROR`	Read the resource’s current state and contact support with its ID and `request_id`.

Message and detail visibility

code is the stable value for programmatic handling. Message wording may improve without changing the code.
message explains the customer-visible problem. Messages do not identify payment or custody vendors or reproduce their raw errors.
details carries useful customer context such as a field, currency, network, resource ID or limit. Internal routing, provider identifiers and gateway responses are omitted.
Legacy application codes on 4xx errors retain their messages and safe context. Unknown 5xx and gateway codes map to public error-family codes; explicit customer messages are preserved. Fee and onboarding codes retain their existing wording.
Support can correlate request_id with internal diagnostics. Internal diagnostics are not part of the customer response.

Wallet limit errors retain currency, network and counts; see Create a wallet.

Messages for common recovery paths

These are current default messages, not strings applications should match. Endpoint-specific validation messages can be more detailed.

Code	Default message	Next step
`WALLET_UNSUPPORTED_COMBINATION`	Wallets aren’t available for `{currency}` on `{network}`.	Choose a configured currency/network pair.
`INSUFFICIENT_FUNDS`	You don’t have enough available funds to complete this transaction.	Fund the selected balance before starting a new operation.
`CREDIT_LIMIT_EXCEEDED`	Operation would exceed the account credit limit.	Reduce the amount or resolve the credit shortfall.
`IDEMPOTENCY_REQUEST_IN_PROGRESS`	A request with this Idempotency-Key is already in progress. Retry the same request shortly.	Back off and reuse the same key and body.
`PAYOUT_FAILED`	The payout could not be completed. Please contact support.	Inspect the payout before deciding whether to create a new one.
`AGREEMENT_ACTION_FAILED`	The Agreement action could not be completed. Please contact support.	Inspect each action result and refresh the Agreement state.

Error response format

Every error returns the same envelope:

{
  "error": {
    "type": "business_rule",
    "code": "CURRENCY_NOT_ENABLED",
    "message": "Currency AUD is not enabled for payout on this account.",
    "details": {
      "currency": "AUD",
      "operation": "payout"
    }
  },
  "request_id": "0f9c1a7e-2b64-4a1d-9f3e-71c2d84b5a60"
}

string

The family of the error: unauthorized, access_denied, kyc_not_approved, validation_error, service_validation, business_rule, delete_blocked, resource_not_found, insufficient_funds, rate_limit_exceeded, request_too_large, gateway (and its gateway_* variants), service_unavailable, or a server-side failure (service, internal_error, configuration).

string

The specific code, always UPPER_SNAKE_CASE. Branch on this value.

string

Human-readable explanation. The wording can change; do not parse it.

object

Structured context, present only on codes that carry it. The keys are listed with each code below.

string

Identifier for this request: your X-Request-ID header when you send one, otherwise a UUID Hop generates. Quote it when contacting support.

Schema validation failures (422 VALIDATION_ERROR) add a validation_errors array naming each offending field, in dot notation for nested fields (platform_fee.amount, address.country); a missing required header appears there under the header’s name:

{
  "error": {
    "type": "validation_error",
    "code": "VALIDATION_ERROR",
    "message": "Amount must be greater than 0"
  },
  "validation_errors": [
    { "field": "amount", "message": "Amount must be greater than 0", "value": "-100", "error_code": "greater_than" }
  ],
  "request_id": "0f9c1a7e-2b64-4a1d-9f3e-71c2d84b5a60"
}

HTTP status codes

Status	Meaning
`200`	Success, including an idempotent replay of a create.
`201`	Created, on first creation by Create Account, Create Transfer, Create Associated Person, Create Virtual Account Group, Create Virtual Account, Upload Document and Simulate Payin. Every other create returns `200`.
`401`	Authentication failed: a missing header, a bad signature, a stale timestamp, a reused nonce, or an unknown or expired API key.
`403`	Access denied: a missing scope, an IP outside your allowlist, KYC not approved, or a customer or account that belongs to another organization.
`404`	The resource does not exist or has been deleted. A resource nested under an account is looked up inside that account, so one belonging to another account is also `404`.
`409`	Idempotency conflict, or a request with the same key still in flight.
`413`	Request body over the endpoint’s limit.
`422`	The request was well formed but a validation or business rule rejected it.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`502`	A required external service failed.
`503`	A required service is temporarily unavailable. Check the operation’s state before retrying a write.

Retrying a request

Check the error code before retrying:

Response	What to do
`429 RATE_LIMIT_EXCEEDED`	Wait for the next clock minute, then retry. See Rate limits.
`409 IDEMPOTENCY_REQUEST_IN_PROGRESS`	Retry after a short backoff with the same key and body.
Idempotency conflict	Resolve the conflicting request; repeating it unchanged will not help.
Temporary `500`, `502`, or `503` failure	Retry with backoff when the endpoint supports it. Configuration and assignment errors require support; see the code reference below.
Other `4xx` errors	Correct the request or resolve the access or resource condition before retrying.

For endpoints that support Idempotency, keep the same key and body. Otherwise, check whether the operation succeeded before submitting it again. Generate fresh authentication headers for each attempt. Failure and recovery covers the procedure for each operation.

Rate limits

Rate limits are applied per API key, per minute, using a fixed clock-minute window. The default is 1000 requests per minute; your key’s limit is set when the key is issued and can be anywhere from 1 to 10000. Exceeding it returns 429:

{
  "error": {
    "type": "rate_limit_exceeded",
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Maximum 1000 requests per minute."
  },
  "request_id": "0f9c1a7e-2b64-4a1d-9f3e-71c2d84b5a60"
}

The response does not carry a Retry-After header today. The counter resets at the top of the next clock minute; sleep until then and retry. If you need a higher limit, contact support.

Error code reference

Authentication and access

`code`	Status	When
`UNAUTHORIZED`	`401`	Missing HMAC header, invalid signature, timestamp more than 300 seconds from server time, reused nonce, or an unknown or expired API key.
`ACCESS_DENIED`	`403`	The API key lacks the scope for this endpoint, the request came from an IP outside the key’s allowlist, or the customer or account belongs to another organization.
`KYC_NOT_APPROVED`	`403`	The customer’s KYC is not approved. `details.kyc_status` carries the current status.
`RESOURCE_NOT_FOUND`	`404`	The resource does not exist, has been deleted, or belongs to another account.
`REQUEST_TOO_LARGE`	`413`	Body over the endpoint’s limit: 1 MB on most routes, 21 MB on Update Account and Upload Document. `details.max_bytes` carries the limit.
`RATE_LIMIT_EXCEEDED`	`429`	Too many requests for this API key in the current minute.

Request validation

`code`	Status	When
`VALIDATION_ERROR`	`422`	Schema validation failed. See `validation_errors`.
`MISSING_REQUIRED_FIELD`	`422`	A conditionally required field was omitted. `details.field` names it.
`INVALID_FIELD_VALUE`	`422`	The value is not acceptable for the field. `details` carry `field` and often `allowed_values`.
`INVALID_FIELD_FORMAT`	`422`	The value has the wrong shape, for example an email without `@` or a Mexican account number that is not an 18-digit CLABE.
`CURRENCY_MISMATCH`	`422`	Two currencies that must match do not, for example a payout currency against its destination.
`DUPLICATE_RESOURCE`	`422`	An equivalent resource already exists. For payout destinations, `details.existing_destination_id` points at it.
`DELETE_BLOCKED`	`422`	The resource still has dependants: a beneficiary with payout destinations, or an associated person a provider already holds or who has signed an agreement.
`DOCUMENT_SUBJECT_MISMATCH`	`422`	An uploaded document’s type does not fit its subject. `details.required_subject` says whether the type needs the account or a person.
`BUSINESS_RULE_VIOLATION`	`422` or `409`	A rule specific to the endpoint failed. See that endpoint’s error table.

Idempotency

`code`	Status	When
`IDEMPOTENCY_CONFLICT`	`409`	The `Idempotency-Key` was already used with a different payload.
`IDEMPOTENCY_REQUEST_IN_PROGRESS`	`409`	An earlier request with the same key is still running. Retry after a short backoff.

Money movement

`code`	Status	When
`INSUFFICIENT_FUNDS`	`422`	The funding balance is below the amount. `details` carry the funding source, currency, requested amount and available balance.
`CURRENCY_NOT_ENABLED`	`422`	The currency is not enabled for that operation on the account.
`AMOUNT_BELOW_MINIMUM`	`422`	The amount is under the minimum for the currency pair.
`AMOUNT_EXCEEDS_MAXIMUM`	`422`	The amount is over the maximum for the currency pair.
`TRADING_ACCOUNT_REQUIRES_SELF_OWNED_BENEFICIARY`	`422`	A withdrawal from the trading account was sent to a beneficiary that is not `self_owned`. Fund it from a virtual account instead.
`CREDIT_LIMIT_EXCEEDED`	`422`	The operation would exceed the account’s credit limit.
`CREDIT_CHECK_UNAVAILABLE`	`503`	The credit check could not be completed. Retry.

Foreign exchange

`code`	Status	When
`FX_PAIR_NOT_ENABLED`	`422`	The currency pair is not enabled on the account. `details` carry `pair` and `enabled_pairs`.
`FX_QUOTE_INVALID`	`422`	The quote is unknown, expired, already executed, or belongs to another account. Request a new quote.
`FX_PRICING_UNAVAILABLE`	`422`	No pricing is available for the pair right now. Retry shortly.
`PLATFORM_FEE_NOT_ENABLED`	`422`	Platform fees are not enabled for your organization.
`PLATFORM_FEE_NOT_ALLOWED`	`422`	Platform fees require an end-customer account of a platform customer.
`PLATFORM_FEE_ACCOUNT_MISSING`	`422`	Your organization has no active fee-collection account.
`PLATFORM_FEE_EXCEEDS_AMOUNT`	`422`	The fee is not smaller than the target amount.

Transfers, virtual accounts and wallets

`code`	Status	When
`TRANSFER_TRADING_TO_TRADING`	`422`	Both legs of the transfer are the trading account. Use FX to convert instead.
`TRANSFER_SAME_LOCATION`	`422`	Source and destination are the same virtual account.
`VIRTUAL_ACCOUNT_INACTIVE`	`422`	The virtual account is not active. `details` carry its id and status.
`WALLET_UNSUPPORTED_COMBINATION`	`422`	That currency is not available on that network.
`LIMIT_EXCEEDED`	`422`	A resource cap was reached, for example one wallet per currency and network. `details` carry `current_count` and `max_allowed`.
`VIRTUAL_ACCOUNT_GROUP_NOT_FOUND`	`404`	The group `type` is not available.
`VIRTUAL_ACCOUNT_GROUP_NOT_ENABLED`	`422`	The group is not `enabled` with `onboarding_status` `approved`.
`VIRTUAL_ACCOUNT_GROUP_ASSIGNMENT_CONFLICT`	`500`	Retrying does not help; contact support.
`SERVICE_FEE_BALANCE_MISSING`	`422`	A creation fee is due in a currency the fee-paying account holds no balance in.
`SERVICE_FEE_ACCOUNT_TYPE_UNSUPPORTED`	`422`	Service fees cannot be charged to this account type.
`SERVICE_FEE_PAYER_UNAVAILABLE`	`422`	No active fee-paying account is available. Contact support.
`VIRTUAL_ACCOUNT_GROUP_ONBOARDING_COUNTRY_LOCKED`	`422`	The country cannot change while Group onboarding is open. `details` identifies the field, Group and existing country.

Approval and operation outcomes

`code`	Status or surface	Customer action
`APPROVAL_NOT_PENDING`, `APPROVAL_ALREADY_PENDING`, `APPROVAL_CONCURRENT_UPDATE`	`422`, portal	Refresh the approval before acting again.
`APPROVAL_NOT_AUTHORIZED`, `SELF_APPROVAL_FORBIDDEN`	`422`, portal	Ask an eligible approver to review the request.
`PAYOUT_FAILED`	Payout failure reason	Inspect the payout and contact support; an accepted payout can fail asynchronously.
`PAYOUT_CANCELLED`	Cancelled payout reason and rejection email	Contact support for more information; reviewer notes remain internal.
`AGREEMENT_ACTION_FAILED`	Per-item Agreement action message	Check every result in the batch; HTTP success alone does not mean every action succeeded.

Service failures

`code`	Status	When
`GATEWAY_ERROR`	`502`	A banking or custody provider rejected or failed the request.
`GATEWAY_AUTH_ERROR`, `GATEWAY_NETWORK_ERROR`, `GATEWAY_REQUEST_ERROR`, `GATEWAY_RESPONSE_ERROR`	`502`	Variants of `GATEWAY_ERROR`; handle them the same way.
`SERVICE_UNAVAILABLE`	`503`	A dependency is temporarily unavailable. Retry with backoff.
`SERVICE_ERROR`	`500`	Unexpected failure while processing the request.
`CONFIGURATION_ERROR`	`500`	Your organization is missing configuration needed for the operation. Contact support.
`INTERNAL_ERROR`	`500`	Unexpected failure.

Getting started

API basics

Endpoints

Webhooks

Error categories and customer actions

Message and detail visibility

Messages for common recovery paths

Error response format

HTTP status codes

Retrying a request

Rate limits

Error code reference

Authentication and access

Request validation

Idempotency

Money movement

Foreign exchange

Transfers, virtual accounts and wallets

Approval and operation outcomes

Service failures

​Error categories and customer actions

​Message and detail visibility

​Messages for common recovery paths

​Error response format

​HTTP status codes

​Retrying a request

​Rate limits

​Error code reference

​Authentication and access

​Request validation

​Idempotency

​Money movement

​Foreign exchange

​Transfers, virtual accounts and wallets

​Approval and operation outcomes

​Service failures

Error categories and customer actions

Message and detail visibility

Messages for common recovery paths

Error response format

HTTP status codes

Retrying a request

Rate limits

Error code reference

Authentication and access

Request validation

Idempotency

Money movement

Foreign exchange

Transfers, virtual accounts and wallets

Approval and operation outcomes

Service failures