> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.bridge.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```json theme={null}
{
  "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`                                             |   |

<Note>
  Validation messages may vary depending on payment rail, transfer type, and configuration.
</Note>

***

## 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.

<Warning>
  Do not reuse an idempotency key with modified parameters. If the request payload changes, generate a new idempotency key.
</Warning>

***

## 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](api-reference/transfers/create-a-transfer)
* [Idempotency guide](api-reference/introduction/idempotence)
* Webhooks and event delivery