---
title: "Errors and rule codes"
description: "Use HTTP statuses, error codes and rule identifiers to handle Nodu API errors."
url: "/guides/api-basics/errors-and-rule-codes/"
index: "/llms.txt"
---

# Errors and rule codes

When a request fails, the Nodu API answers with an HTTP status and a JSON error object. The status and the object tell you what went wrong and whether to send the request again. Start with the HTTP `status`, then read `code`. For `business_rule_violation`, read `rule` to choose the recovery action. The tables below cover documented errors and rules used in these guides.

## The error object

| Field | Present in | Meaning |
|---|---|---|
| `status` | Every error | The HTTP status code of the response. |
| `title` | Every error | A short summary of the kind of error. It is the same for every error of that kind. |
| `code` | Most errors | A machine-readable error code, such as `validation_failed`. Some errors have no `code`: `400` and `401` responses and the `403` response for a request from an IP address that is not allowed. |
| `detail` | Some errors | An explanation of this specific error, in English. |
| `errors` | `validation_failed` | One entry for each value that failed validation. |
| `rule` | `business_rule_violation` | The identifier of the rule that the request broke. |

A validation error lists each value that failed. `propertyPath` names the field, with a period between nested fields:

```json
{
  "code": "validation_failed",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    {
      "propertyPath": "application.individual.nationality",
      "message": "This field is required."
    },
    {
      "propertyPath": "application.individual.questionnaire.industryDescription",
      "message": "This field is required."
    }
  ]
}
```

A business rule violation names the rule in `rule`:

```json
{
  "code": "business_rule_violation",
  "title": "Business rule violation",
  "status": 422,
  "detail": "No active payment channel for currency 'eur' and rail 'sepa'.",
  "rule": "payment_channel_not_active"
}
```

An error can carry more fields. For example, `feature_not_enabled` adds `feature`. Ignore the fields that you do not know.

Use `status`, `code` and `rule` to decide how your code handles the error. `title` and `detail` explain the error for people. Log these fields. Do not compare their text in code.

Each operation in the [API Reference](/api/index.md) lists its error responses and examples.

## HTTP statuses

### Successful responses

| Status | Meaning | What you do |
|---|---|---|
| `200`, `201` | The request succeeded. `201` means that Nodu created an object. | Read the response. |
| `202` | Nodu accepted the request for processing. The response does not confirm completion. | Follow the status of the object through webhooks, or retrieve the object. |
| `204` | The request succeeded. The response has no body. | Nothing. |

### Error responses

| Status | Meaning | What you do |
|---|---|---|
| `400` | The request is malformed. For example, the body is not valid JSON. | Correct the request. |
| `401` | The API key is missing or not valid. | See [Authentication](/guides/api-basics/authentication/index.md). |
| `403` | The API key is valid, but Nodu does not allow the request. | Read `code`. See [Authentication](/guides/api-basics/authentication/index.md) for a request from an IP address that is not allowed. |
| `404` | The object does not exist, or you have no access to it. | Check the ID and the environment. |
| `409` | The request conflicts with an existing object or with another request. | Read `code`: see [Error codes](#error-codes) for `idempotency_mismatch`, `resource_busy` and `resource_conflict`. |
| `422` | Nodu understood the request but cannot carry it out. | See [Validation errors and business rule violations](#validation-errors-and-business-rule-violations). |
| `500` | An unexpected error at Nodu. | Reconcile changes before retrying: see [Which requests to retry](#which-requests-to-retry). |

## Validation errors and business rule violations

Both kinds of error have the status `422`. The `code` field tells them apart.

### Validation errors

The code `validation_failed` means that a value in the request is missing or not valid. The `errors` field has one entry for each problem:

- `propertyPath` names the field. A nested field has a dotted path, such as `source.amount`. `propertyPath` can be `null` when the problem concerns the request as a whole.
- `message` says what is wrong, in English.

Correct the values. Then send the request again.

In your interface, you can show each `message` next to the field that `propertyPath` names.

[Submit an application for evaluation](/api/tag/customers/post-v1-customers-customerid-applications-applicationid-submit.md) uses this format to list the information and the documents that an application still needs.

### Business rule violations

The code `business_rule_violation` means that the request is well formed, but the operation is not allowed in the current state of an object. For example, you create a transfer for a customer whose `status` is not `active`. The `rule` field identifies the rule. `detail` explains why this request failed.

Look up `rule` in the [Rule identifiers](#rule-identifiers) table. Take the action listed for that rule. For example, you may need to complete the customer's onboarding, activate a [payment channel](/guides/transfers/payment-channels/index.md), or create a new quote. Then send the request again.

## Which requests to retry

- **Reconcile an uncertain outcome** after a `500`, timeout or dropped connection before retrying an operation that changes data or moves money. Follow [Idempotency](/guides/api-basics/idempotency/index.md#retry-a-request-that-timed-out); contact Nodu if you cannot establish the outcome.
- **Retry** after a `409` response with `code=resource_busy`: Nodu did not carry out your request.
- **Do not retry other errors unchanged.** Correct the request or resolve the state conflict first.

[Retry decisions](/guides/api-basics/idempotency/index.md#retry-decisions) says how long to wait and what to send in each case.

## Error codes

This table lists the values of `code` that the API reference documents. The API can return a code that is not in the table. Handle an unknown code by its HTTP status.


| `code` | HTTP status | Meaning | What you do |
|---|---|---|---|
| `access_denied` | `403` | The API key is not allowed to make this request. | Do not retry. Contact Nodu. |
| `business_rule_violation` | `422` | The request is well formed, but the operation is not allowed in the current state of the customer, the transfer or another object. The `rule` field identifies the rule. | Look up `rule` under [Rule identifiers](#rule-identifiers). |
| `destination_not_supported` | `422` | The combination of currency, country and rail you asked about is not available. | Call [List external account destinations](/api/tag/external-accounts/get-v1-external-accounts-destinations.md) and choose one of the combinations it returns. |
| `feature_not_enabled` | `403` | The operation belongs to a feature that is not included in your integration agreement with Nodu. The `feature` field names it. | Do not retry. Contact Nodu if you need the feature. |
| `forbidden` | `403` | The action is not allowed. The sandbox simulation operations return this code when a simulation is not available, for example outside the sandbox. | Call the simulation operations in the sandbox only. |
| `idempotency_mismatch` | `409` | The idempotency key has a stored successful response for a different request body. | Restore the original body to recover that response. Use a new key only for an intentionally separate operation. See [Idempotency](/guides/api-basics/idempotency/index.md#how-nodu-handles-a-key). |
| `internal_error` | `500` | An unexpected error at Nodu. | Reconcile changes before retrying: see [Which requests to retry](#which-requests-to-retry). |
| `resource_busy` | `409` | Another request is changing the same object, or Nodu is still processing an earlier request with the same `Idempotency-Key`. Nodu did not carry out this attempt. | Retry after the number of seconds in `Retry-After`. With a `POST`, keep the same idempotency key and exact body; an earlier request may still complete. |
| `resource_conflict` | `409` | The request conflicts with an existing object. For example, the `clientReferenceId` you sent is already used by another object of the same kind. | For a duplicate `clientReferenceId`, find the existing object and use it, or send a reference that is not in use for an intentionally separate object. |
| `resource_missing` | `404` | The object does not exist, or you have no access to it. | Check the ID. Check that you call the environment in which the object was created. |
| `validation_failed` | `422` | One or more values in the request are missing or not valid. The `errors` field lists them. | Correct the fields named in `errors` and send the request again. |

## Rule identifiers

This table includes rules documented in the API Reference and rules used by these guides. The list is not exhaustive. Your code must handle a `rule` that is not in the table. Do not retry the request. Log `rule` and `detail`. In your interface, you can show the customer a general error message.

Rules marked "Sandbox only" come from the operations that simulate funding and the verification of a crypto wallet in the sandbox, the test environment. Rules about a share token concern a customer that you create from an applicant you have already verified: see [onboarding with a share token](/guides/customers/api-onboarding/sumsub-sharing/index.md).


| `rule` | Meaning | What you do |
|---|---|---|
| `applicant_import_identity_mismatch` | The email or phone number on the shared applicant profile differs from the one you sent for the customer. | Correct the contact details, generate a new share token and create the customer again. |
| `applicant_import_not_permitted` | Creating a customer from a share token is not included in your integration agreement with Nodu. | Send the request without the `import` block. |
| `applicant_import_not_reusable` | The shared applicant profile does not meet the verification requirements for this application. | Complete the applicant's verification on your side, then generate a new share token. |
| `application_not_editable` | The application cannot be changed now. An application can be updated only while it is a draft or after Nodu has asked for a resubmission. | Wait for the outcome of the review. See [Resubmission and rejection](/guides/customers/resubmission-and-rejection/index.md). |
| `cannot_enrich_self_owned_external_account` | You sent `counterparty` data for a [first-party external account](/guides/transfers/external-accounts/first-party-and-third-party-accounts/index.md). A first-party account has no counterparty to update. | Send the request without `counterparty`. |
| `counterparty_already_archived` | The counterparty is archived. It cannot be updated or archived again. | Create a new counterparty if you still need one. |
| `counterparty_archived` | The counterparty you named is archived and cannot be used for a new external account. | Use another counterparty, or create a new one. |
| `customer_not_accepted_tos` | The customer has not accepted Nodu's Terms of Service yet, so Nodu cannot issue a verification link. | Obtain the acceptance first: [Retrieve a link to ToS acceptance page for a customer](/api/tag/customers/get-v1-customers-customerid-tos-acceptance-link.md). |
| `customer_not_active` | The customer's `status` is not `active`, so the operation is not allowed for this customer. | Retrieve the customer and read `status`. [How onboarding works, and customer statuses](/guides/customers/how-onboarding-works/index.md) says what you do in each status. |
| `destination_currency_mismatch` | The `currency` you sent for the destination differs from the currency of the destination account. | Send the currency of the destination account. `detail` names both currencies. |
| `external_account_already_archived` | The external account is archived. It cannot be updated or archived again. | Create a new external account if you still need one. |
| `import_token_expired` | The share token has expired or was already used. | Generate a new share token and create the customer again, with a new `Idempotency-Key`. |
| `import_token_invalid` | The share token is not valid. | Check the values you used to generate the token, then generate a new one. |
| `insufficient_transfer_amount` | The amount does not cover the fees of the transfer. `detail` states the amount and the fees. | Increase the amount, or lower `developerFee`. |
| `nodu_account_rail_not_allowed` | Sandbox only. The source of the transfer is a Nodu wallet (rail `wallet`, or the deprecated `nodu_account`), so there is no incoming payment to simulate. | Do not simulate funding for this transfer. |
| `payment_channel_not_active` | The customer has no `active` payment channel for this currency and rail. | List the customer's payment channels and activate the one you need. See [Payment channels](/guides/transfers/payment-channels/index.md). |
| `quote_already_accepted` | The quote was already used for a transfer. | Create a new quote. |
| `quote_mismatch` | The transfer parameters do not match the quote. | Use the quoted amounts, currencies and rails, or obtain a matching quote and confirm it with the customer. |
| `quote_expired` | The quote has expired. | Call [Update a quote](/api/tag/quotes/patch-v1-quotes-quoteid.md) or create a new quote, and present the new figures to the customer. See [Quotes and exchange rates](/guides/transfers/quotes-and-exchange-rates/index.md). |
| `relay_wrong_status` | Sandbox only. The relay is not `active`, so funding cannot be simulated. | Wait until the relay is `active`. |
| `reliance_application_not_permitted` | Sending application data through the API is not included in your integration agreement with Nodu. | Create the customer without the `application` block. See [Onboarding models](/guides/customers/onboarding-models/index.md). |
| `remitter_not_supported` | Sandbox only. The simulated payment cannot carry the `remitter` details you sent. | Send the request again without `remitter`. |
| `tos_pre_acceptance_not_permitted` | Recording terms acceptance through the API is not enabled for your integration. | Use [hosted terms acceptance](/guides/customers/hosted-onboarding/index.md#2-obtain-acceptance-of-the-terms). |
| `transfer_cannot_be_cancelled` | The transfer can no longer be canceled. | Retrieve its current state and follow [Track a transfer](/guides/transfers/track-a-transfer/index.md). |
| `transfer_amount_below_minimum` | The amount is below the minimum for this transfer. `detail` states the minimum. | Increase the amount. |
| `transfer_wrong_status` | Sandbox only. The transfer is not in the `awaiting_funds` state, so funding cannot be simulated. | Simulate funding only while the transfer is `awaiting_funds`. |
| `wallet_not_active` | The Nodu wallet you named as the source or destination of a transfer, or as the destination of a relay, has `status=suspended` or `status=closed`. `detail` states which. | Retrieve the wallet and read its `status`. Use a wallet with `status=active`. When a suspended wallet becomes `active` again, Nodu sends [`v1.wallet.activated`](/guides/api-basics/webhooks/index.md#event-types). |
| `wallet_verification_rail_not_crypto` | Sandbox only. The side of the transfer you chose does not run on a blockchain rail, so it has no crypto wallet to verify. | Choose the other `side`. |
| `wallet_verification_side_required` | Sandbox only. No side of the transfer is waiting for the verification of a crypto wallet. | Send `side` to simulate a verification anyway. |
| `wallet_verification_wallet_unknown` | Sandbox only. The crypto wallet address on that side of the transfer is not known yet. | Simulate the funding of the transfer first. |

## Next steps

- [Idempotency](/guides/api-basics/idempotency/index.md): retry a `POST` request without repeating the operation.
- [Receive and verify webhooks](/guides/api-basics/webhooks/index.md): learn about state changes without polling.
- [Track and cancel a transfer](/guides/transfers/track-a-transfer/index.md): what to do when a transfer itself fails.
- [Simulate funding in the sandbox](/guides/sandbox/simulate-funding/index.md): the operations behind the rules marked "Sandbox only".
