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:
{
"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:
{
"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 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. |
403 | The API key is valid, but Nodu does not allow the request. | Read code. See Authentication 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 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. |
500 | An unexpected error at Nodu. | Reconcile changes before retrying: see 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:
propertyPathnames the field. A nested field has a dotted path, such assource.amount.propertyPathcan benullwhen the problem concerns the request as a whole.messagesays 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 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 table. Take the action listed for that rule. For example, you may need to complete the customer's onboarding, activate a payment channel, 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; contact Nodu if you cannot establish the outcome. - Retry after a
409response withcode=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 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. |
destination_not_supported | 422 | The combination of currency, country and rail you asked about is not available. | Call List external account destinations 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. |
internal_error | 500 | An unexpected error at Nodu. | Reconcile changes before retrying: see 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.
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. |
cannot_enrich_self_owned_external_account | You sent counterparty data for a first-party external account. 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. |
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 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. |
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 or create a new quote, and present the new figures to the customer. See Quotes and exchange rates. |
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. |
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. |
transfer_cannot_be_cancelled | The transfer can no longer be canceled. | Retrieve its current state and follow Track a transfer. |
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. |
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: retry a
POSTrequest without repeating the operation. - Receive and verify webhooks: learn about state changes without polling.
- Track and cancel a transfer: what to do when a transfer itself fails.
- Simulate funding in the sandbox: the operations behind the rules marked "Sandbox only".