> For the complete documentation index, see [llms.txt](https://docs.txn.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.txn.io/api-basics/errors.md).

# Errors

The API reports every failure with an HTTP status of 4xx or 5xx and a JSON:API error document. Match on `code`, which is stable. The wording of `title` and `detail` can change.

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Invalid parameter",
      "code": "order_invalid",
      "detail": "order must be one of: created_at, updated_at",
      "source": {
        "pointer": "/data/attributes/order"
      }
    }
  ]
}
```

**Error object**

| Field            | Description                                                                                                                                                                |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`         | HTTP status of the error, as an integer. The response status is the status of the first error.                                                                             |
| `title`          | Short, human-readable summary.                                                                                                                                             |
| `code`           | Machine-readable identifier. Match on this.                                                                                                                                |
| `detail`         | Human-readable explanation. Often includes the values involved, for example the minimum amount.                                                                            |
| `source.pointer` | Present when the error concerns one attribute: a JSON pointer such as `/data/attributes/amount`. Query parameters use the same form, for example `/data/attributes/order`. |

Error responses always carry `Content-Type: application/vnd.api+json`. Validation can return several errors at once, one per attribute:

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Invalid parameter",
      "code": "order_invalid",
      "detail": "order must be one of: created_at, updated_at",
      "source": {
        "pointer": "/data/attributes/order"
      }
    },
    {
      "status": 422,
      "title": "Invalid parameter",
      "code": "order_type_invalid",
      "detail": "order_type must be one of: asc, desc",
      "source": {
        "pointer": "/data/attributes/orderType"
      }
    }
  ]
}
```

## HTTP status codes

| Status | `code`                  | When                                                                                                                                                                                                                                                                                                                                       |
| ------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400    | `bad_request`           | The body is not valid JSON, the `Content-Type` is not `application/vnd.api+json`, or a required parameter is missing altogether, for example `paymentType` when creating a payment link.                                                                                                                                                   |
| 401    | `unauthorized`          | The `Authorization` header is missing, the API key is unknown or revoked, the company is not active, or the request comes from an IP address outside the key's allow list. The response also carries `WWW-Authenticate: Bearer realm=Application`. See [Authenticating the API](https://docs.txn.io/api-basics/authenticating-the-api.md). |
| 403    | `forbidden`             | The API key only has read permission and the request writes, or API access is disabled for your company.                                                                                                                                                                                                                                   |
| 404    | `not_found`             | The path does not exist.                                                                                                                                                                                                                                                                                                                   |
| 404    | `<resource>_not_found`  | The ID in the path, or an ID referenced in the body, does not exist or belongs to another company. Examples: `account_not_found`, `invoice_not_found`, `payout_not_found`, `network_not_found`, `bank_account_not_found`.                                                                                                                  |
| 422    | see below               | The request is well-formed but cannot be processed: a parameter failed validation, the record would be invalid, or a business rule rejected it.                                                                                                                                                                                            |
| 429    | `too_many_requests`     | The rate limit was exceeded. See [Rate limits](https://docs.txn.io/api-basics/rate-limits.md).                                                                                                                                                                                                                                             |
| 500    | `internal_server_error` | Unexpected failure. Retry later. If it persists, contact support with the request and the time it was made.                                                                                                                                                                                                                                |

## Validation errors (422)

Three code patterns cover request validation. `detail` says what is wrong and `source.pointer` names the attribute.

| Pattern                   | Title                   | When                                                                                                                                                                                                                                                                    |
| ------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<parameter>_invalid`     | Invalid parameter       | A body attribute or query parameter is missing, has the wrong type, or has an unsupported value. Examples: `order_invalid`, `amount_invalid`, `reference_invalid`.                                                                                                      |
| `<resource>_invalid`      | Invalid attribute       | The record would violate a constraint, most often uniqueness: `account_invalid` (subaccount label already used), `channel_invalid` (channel reference already used), `payment_link_invalid` (payment link reference already used), `invoice_invalid`, `payout_invalid`. |
| `invalid_json_api_object` | Invalid JSON:API object | The body is JSON but not a JSON:API document with a single `data` resource object.                                                                                                                                                                                      |

## Business rule errors (422)

Each has a fixed `code`. `detail` may include the values involved.

**Common to several endpoints**

| Code                               | When                                                                                                                                                                                                                                                                                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `exchange_unavailable`             | Currency conversion is temporarily unavailable and the request needs one: different billed and charged currencies, a fiat-funded payout, a quote. Retry later.                                                                                                                                                                             |
| `account_has_insufficient_balance` | The account to be debited does not hold the amount, fees included. Returned by transfers, quotes, payouts and bank withdrawals.                                                                                                                                                                                                            |
| `amount_must_be_positive`          | The amount is negative.                                                                                                                                                                                                                                                                                                                    |
| `amount_below_minimum`             | The amount is below the minimum for the currency pair. `detail` states the minimum. Returned by invoices, payouts and quotes.                                                                                                                                                                                                              |
| `amount_above_maximum`             | The amount is above the maximum for the currency pair. `detail` states the maximum. Returned by invoices, payouts and quotes.                                                                                                                                                                                                              |
| `currency_pair_not_supported`      | The combination of currencies, in that direction, is not enabled for your company. Returned by invoices, quotes and exchange rates.                                                                                                                                                                                                        |
| `<role>_account_unavailable`       | An account involved in the request has been closed. The prefix names its role: `account_unavailable`, `from_account_unavailable`, `to_account_unavailable`, `target_account_unavailable`, `pay_account_unavailable`, `account_charged_unavailable`, `account_paid_unavailable`, `charged_account_unavailable`, `paid_account_unavailable`. |

**Accounts, transfers and addresses**

| Code                                   | Endpoint                                   | When                                                                              |
| -------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- |
| `account_transfer_currencies_mismatch` | Creating transfer                          | The two accounts and `currency` are not all the same currency.                    |
| `network_not_found` (404)              | Creating account address, creating channel | The network does not exist or is not enabled.                                     |
| `network_account_mismatch`             | Creating account address                   | The network's currency is not the account's currency.                             |
| `invalid_address`                      | Validating address, creating payout        | The address is not valid on that network. `detail` describes the expected format. |
| `address_has_high_risk_score`          | Validating address, creating payout        | Compliance screening rejected the address.                                        |
| `binance_pay_invalid_receiver`         | Validating Binance ID, creating payout     | The Binance ID is not valid.                                                      |

**Channels**

| Code                     | Endpoint         | When                                                                              |
| ------------------------ | ---------------- | --------------------------------------------------------------------------------- |
| `channel_pair_not_found` | Creating channel | No channel is available from `localCurrency` to `targetCurrency` on `payNetwork`. |

**Exchange**

| Code                               | Endpoint                         | When                                                                         |
| ---------------------------------- | -------------------------------- | ---------------------------------------------------------------------------- |
| `incorrect_currency`               | Previewing quote, creating quote | `amountCurrency` is neither the charged nor the received account's currency. |
| `exchange_quote_expired`           | Confirming quote                 | `expiresAt` has passed. Create a new quote.                                  |
| `quote_incorrect_state_transition` | Confirming quote                 | The quote is not pending. It was already confirmed or has failed.            |
| `currency_not_found` (404)         | Reading exchange rates in bulk   | `currency_code` is unknown.                                                  |

**Invoices**

| Code                            | Endpoint                                        | When                                                                                                                      |
| ------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `network_currency_mismatch`     | Creating invoice, creating payment link payment | `network` does not carry `chargedCurrency`.                                                                               |
| `charge_currency_not_supported` | Creating invoice                                | `chargedCurrency` must be a cryptocurrency.                                                                               |
| `payment_methods_conflict`      | Creating invoice                                | `paymentMethods` contains more than one method.                                                                           |
| `invalid_url`                   | Creating invoice                                | `successRedirectUrl` or `unsuccessRedirectUrl` is not a valid URL. `detail` says which.                                   |
| `reference_duplicate`           | Creating invoice, creating payment link         | `reference` is already used by one of your invoices. For payment links, also by one of your payouts that has not expired. |

**Payment links**

| Code                           | Endpoint                                             | When                                                                                      |
| ------------------------------ | ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `unsupported_pay_currency`     | Creating payment link                                | `payCurrencies` contains a code that is not a cryptocurrency.                             |
| `currency_not_balanceable`     | Creating payment link                                | The account currency cannot hold a balance. Set `accountCurrency` to a tradable currency. |
| `expires_at_too_long`          | Creating payment link                                | `expires_at` is more than 30 days ahead.                                                  |
| `payment_link_not_found` (404) | Creating payment link payment, expiring payment link | The link is no longer active: it expired, was paid, or was expired by you.                |
| `disallowed_charged_currency`  | Creating payment link payment                        | `chargedCurrency` is not one of the link's `payCurrencies`.                               |

**Payouts**

| Code                              | Endpoint                         | When                                                                                      |
| --------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
| `payout_currency_pair_not_found`  | Creating payout, drafting payout | No payout pair from `chargeCurrency` to the currency of `payNetwork`.                     |
| `amount_below_minimum_after_fees` | Creating payout, drafting payout | Nothing would be left to send once fees are deducted.                                     |
| `inconsistent_parameters`         | Creating payout, drafting payout | The deprecated `absorbFees` contradicts `absorbProcessingFee` or `absorbNetworkFee`.      |
| `beneficiary_info_required`       | Creating payout, drafting payout | The Travel Rule applies to this payout and beneficiary details are missing or incomplete. |
| `refunds_to_deposit_address`      | Creating payout                  | A refund cannot be sent to a Txn deposit address.                                         |
| `payout_expired`                  | Confirming payout draft          | The draft was not confirmed within 30 seconds.                                            |

**Bank withdrawals**

| Code                           | Endpoint                                             | When                                              |
| ------------------------------ | ---------------------------------------------------- | ------------------------------------------------- |
| `bank_withdrawal_unavailable`  | Previewing bank withdrawal, creating bank withdrawal | Bank withdrawals are not enabled for the account. |
| `bank_account_not_found` (404) | Previewing bank withdrawal, creating bank withdrawal | `bankAccountId` is unknown.                       |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.txn.io/api-basics/errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
