Transfer errors & recovery

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 response format

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_rail
• source.from_address
• source.amount
• source.external_account_id
• source.bridge_wallet_id
• source.batch_settlement_schedule_id
• destination.currency
• destination.external_account_id
• destination.payment_rail
• developer_fee
• features.allow_any_from_address
• amount

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

1. Validate required fields before making the request.
2. Use idempotency keys for create operations.
3. Log both the HTTP status code and the error code.
4. Inspect source.key for invalid_parameters responses.
5. 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

• Transfers API reference
• Idempotency guide
• Webhooks and event delivery