Skip to main content

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​

FieldPresent inMeaning
statusEvery errorThe HTTP status code of the response.
titleEvery errorA short summary of the kind of error. It is the same for every error of that kind.
codeMost errorsA 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.
detailSome errorsAn explanation of this specific error, in English.
errorsvalidation_failedOne entry for each value that failed validation.
rulebusiness_rule_violationThe 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​

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

Error responses​

StatusMeaningWhat you do
400The request is malformed. For example, the body is not valid JSON.Correct the request.
401The API key is missing or not valid.See Authentication.
403The 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.
404The object does not exist, or you have no access to it.Check the ID and the environment.
409The request conflicts with an existing object or with another request.Read code: see Error codes for idempotency_mismatch, resource_busy and resource_conflict.
422Nodu understood the request but cannot carry it out.See Validation errors and business rule violations.
500An 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:

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

codeHTTP statusMeaningWhat you do
access_denied403The API key is not allowed to make this request.Do not retry. Contact Nodu.
business_rule_violation422The 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_supported422The 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_enabled403The 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.
forbidden403The 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_mismatch409The 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_error500An unexpected error at Nodu.Reconcile changes before retrying: see Which requests to retry.
resource_busy409Another 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_conflict409The 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_missing404The 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_failed422One 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.

ruleMeaningWhat you do
applicant_import_identity_mismatchThe 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_permittedCreating 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_reusableThe 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_editableThe 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_accountYou 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_archivedThe counterparty is archived. It cannot be updated or archived again.Create a new counterparty if you still need one.
counterparty_archivedThe 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_tosThe 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_activeThe 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_mismatchThe 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_archivedThe external account is archived. It cannot be updated or archived again.Create a new external account if you still need one.
import_token_expiredThe 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_invalidThe share token is not valid.Check the values you used to generate the token, then generate a new one.
insufficient_transfer_amountThe 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_allowedSandbox 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_activeThe 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_acceptedThe quote was already used for a transfer.Create a new quote.
quote_mismatchThe 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_expiredThe 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_statusSandbox only. The relay is not active, so funding cannot be simulated.Wait until the relay is active.
reliance_application_not_permittedSending 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_supportedSandbox only. The simulated payment cannot carry the remitter details you sent.Send the request again without remitter.
tos_pre_acceptance_not_permittedRecording terms acceptance through the API is not enabled for your integration.Use hosted terms acceptance.
transfer_cannot_be_cancelledThe transfer can no longer be canceled.Retrieve its current state and follow Track a transfer.
transfer_amount_below_minimumThe amount is below the minimum for this transfer. detail states the minimum.Increase the amount.
transfer_wrong_statusSandbox 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_activeThe 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_cryptoSandbox 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_requiredSandbox 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_unknownSandbox only. The crypto wallet address on that side of the transfer is not known yet.Simulate the funding of the transfer first.

Next steps​