Transfers API Errors
The Transfers API uses standard HTTP status codes and structured error responses to indicate validation issues, permission failures, resource conflicts, upstream dependency failures, and internal errors.
Error responses include:
- an HTTP status code
- a machine-readable
code
- a human-readable
message
- in some cases, additional context such as
source.key for field-level validation failures
Example error response
{
"code": "invalid_parameters",
"message": "Malformed or invalid field values",
"source": {
"key": "source.payment_rail"
}
}
HTTP status and error codes
400 Bad Request
Returned when the request is malformed, contains invalid parameters, or fails request preconditions.
| Code | Description |
|---|
invalid_parameters | One or more request fields are invalid |
invalid_json | Request body could not be parsed |
not_found | A referenced resource does not exist |
bad_request | Generic bad request |
frozen | Customer or developer account is frozen or paused |
has_not_accepted_tos | Customer has not accepted Terms of Service |
requires_active_kyc_status | Customer KYC status is not active |
deactivated_external_account | Destination external account has been deactivated |
duplicate_record | Idempotency key was reused with different parameters |
not_truly_idempotent | Same idempotency key was used with a different request body |
invalid_geographic_location | Customer is in an unsupported state or region |
missing_address_data | Required address data is missing or incomplete |
cards_endorsement_approval_required | Cards endorsement has not yet been approved |
401 Unauthorized
Returned when the requested feature or rail is not enabled for the developer account.
| Code | Description |
|---|
not_allowed | Requested rail or feature is not enabled |
403 Forbidden
Returned when the request is understood but not permitted.
| Code | Description |
|---|
missing_required_endorsements | Customer lacks a required endorsement |
developer_limits_exceeded | Developer-level transaction limits have been exceeded |
endorsement_requirements_not_met | Endorsement criteria are not satisfied |
forbidden | General permission denied |
404 Not Found
Returned when the transfer or related resource cannot be found.
| Code | Description |
|---|
resource_not_found | Requested resource was not found |
409 Conflict
Returned when the requested action is not allowed in the transfer’s current state.
| Code | Description |
|---|
resource_state_conflict | Resource state does not allow the requested operation |
422 Unprocessable Entity
Returned when the request is structurally valid but cannot be processed.
| Code | Description |
|---|
unprocessable_entity | Request cannot be processed in its current form |
424 Failed Dependency
Returned when an upstream dependency fails during processing.
| Code | Description |
|---|
external_dependency_failed | External service dependency failed |
500 Internal Server Error
Returned when an unexpected internal error occurs.
| Code | Description |
|---|
500 | Unexpected internal error |
503 Service Unavailable
Returned when the service is temporarily unavailable.
| Code | Description | |
|---|
503 | Temporary service unavailability | |
| | |
Validation errors
Requests that fail with invalid_parameters may include a source.key value identifying the specific field that caused the failure.
Common fields
source.payment_railsource.from_addresssource.amountsource.external_account_idsource.bridge_wallet_idsource.batch_settlement_schedule_iddestination.currencydestination.external_account_iddestination.payment_raildeveloper_feefeatures.allow_any_from_addressamount
Common validation messages
| Field | Example message | |
|---|
source.payment_rail | Must be ach | |
source.payment_rail | Must be wire or ach_push | |
source.payment_rail | ACH pull/debit not supported | |
source.from_address | must be set for this payment rail | |
source.from_address | Not a valid address | |
source.amount | Source amount must be specified | |
source.amount | must be at least X for destination amount of Y | |
source.external_account_id | Not a valid external account | |
source.bridge_wallet_id | cannot be set for this payment rail | |
source.batch_settlement_schedule_id | must be set | |
destination.currency | Invalid currency pair for fixed output transfers: X -> Y | |
destination.external_account_id | The external account does not support swift transfers | |
destination.external_account_id | must be a European IBAN account with EUR currency for SEPA transfers | |
developer_fee | cannot be set on this type of transfer | |
features.allow_any_from_address | is not supported for prefunded payment rail | |
amount | Amount has precision loss | |
amount | Not a valid float string | |
Validation messages may vary depending on payment rail, transfer type, and configuration.
Idempotency errors
The Transfers API enforces idempotency for repeated requests using the same idempotency key.
Possible idempotency errors
| Code | Description | |
|---|
duplicate_record | Idempotency key was reused with different parameters | |
not_truly_idempotent | Same idempotency key was submitted with a different request payload | |
Best practice
Reuse an idempotency key only for exact retries of the same request.
Do not reuse an idempotency key with modified parameters. If the request payload changes, generate a new idempotency key.
Error handling guidance
Use the following guidance when determining whether an error should be retried.
| Status | Category | Retry guidance |
|---|
400 | Validation or request issue | Do not retry until the request is corrected |
401 | Feature or rail not enabled | Do not retry without account configuration changes |
403 | Permission, endorsement, or limits issue | Do not retry unless eligibility or limits change |
404 | Missing resource | Do not retry unless the referenced resource becomes available |
409 | Invalid state transition | Retry only after the resource reaches a valid state |
422 | Business logic failure | Do not retry unless request data changes |
424 | Upstream dependency failure | Retry according to your retry policy |
500 | Internal server error | Retry with backoff if appropriate |
503 | Temporary service unavailability | Retry with backoff |
Recommended handling pattern
- Validate required fields before making the request.
- Use idempotency keys for create operations.
- Log both the HTTP status code and the error
code.
- Inspect
source.key for invalid_parameters responses.
- Retry only transient failures such as
424, 500, and 503.
Notes
- Validation-related exceptions are returned as structured JSON.
- Unhandled exceptions fall back to a
500 response with a generic message and reference code.
- Some responses, such as
missing_required_endorsements, may include context-specific messaging depending on the payment rail or configuration involved.
See also
