Errors
Every answer, success or failure, has the same envelope.
{ "code": "NB40301", "message": "account not permitted", "data": null }
| Field | Meaning |
|---|---|
code | A short code. 000000 means success. |
message | A short description for people. Do not parse it. |
data | The result on success. Empty on failure. |
Match on code. Every error code is a string that starts with NB.
Every code comes from NAS. When card processing refuses a call, NAS answers with one of its own codes and its own message. Card processing codes are never passed through.
NAS error codes
| Code | HTTP status | Meaning | What to do |
|---|---|---|---|
NB40001 | 400 | The call needs an accountId and none was sent. | Add the accountId. |
NB40002 | 400 | The request is malformed. The message says what is wrong, for example a bad upload or missing identity fields. | Fix the request. Do not retry it as it is. |
NB40101 | 401 | The client id, one-time code or refresh token is not valid. | Start again from authentication, step 1. |
NB40301 | 403 | The account is not one of yours. | Use an account id from your own account list. |
NB40302 | 403 | The resource (card, cardholder, wallet, budget) is not one of yours. | Check the id. |
NB40303 | 403 | This endpoint is not enabled for your client. Calls that read card numbers or PINs, or send funds out, are never enabled. | Do not retry. If you need the call, ask NAS. |
NB40304 | 403 | Your client is suspended. | Contact NAS. |
NB40305 | 403 | The call came from an IP address that is not registered for your client. | Call from a registered address, or ask NAS to add yours. |
NB40306 | 403 | The service is not enabled for your client. | Contact NAS. |
NB40310 | 403 | The KYC call names a different person from the one first submitted for this account. | Submit the same person, or use a different account. |
NB40311 | 403 | The KYC call names a person who is already verified on another account. | Use the account that person already has. |
NB40312 | 403 | The request or the answer involves a resource reserved to NAS. | Do not retry. Contact NAS. |
NB40400 | 404 | The path is not part of this API. | Check the path against the reference. |
NB42902 | 429 | You have used your request allowance for the minute. | Wait for the Retry-After header, then repeat the call as it was. |
NB50201 | 502 | The call was made, but NAS held back the answer because it could not return it safely. | Read the resource before you retry a call that creates something. See below. |
NB50301 | 503 | The card processing service is unavailable. | Retry later with the same idempotency key. |
NB50302 | 503 | NAS could not record the call, so it was not made. | Retry later with the same idempotency key. |
Access token code
| Code | HTTP status | Meaning | What to do |
|---|---|---|---|
NB40102 | 401 | The access token is not valid or has expired. | Refresh the token, then retry once. |
Card processing codes
When card processing refuses a call, you get one of these codes. Where a message names a field, it ends with the field name, for example A parameter is not valid: cardholderId.
| Code | HTTP status | Meaning | What to do |
|---|---|---|---|
NB40010 | 400 | A required value is missing. The message names it. | Add it and send the request again. |
NB40011 | 400 | A parameter is not valid. The message names it. Typical causes are a wrong enum value, an id that is not a UUID, or an unsupported currency. | Correct it and send the request again. |
NB40012 | 400 | A phone number or email address is not in a valid format. | Check it, including the country code. |
NB40013 | 400 | A name or address field is too short or not in a valid format. | Check the name and address fields. The country must be a two-letter ISO 3166-1 code. |
NB40014 | 400 | The text contains characters that are not supported. | Remove accents, symbols and other special characters. |
NB40015 | 400 | The uploaded file cannot be accepted. | Check that it is not empty, is within the size limit and that its extension matches its format. |
NB40016 | 400 | The identity or business details are not valid. The message names the part. | Correct them and submit again. |
NB40017 | 400 | A value or option is not supported. The message names it. | Check the API reference for the values the call accepts. |
NB40018 | 400 | The card limit cannot be set. | Limits can be set only on active or frozen cards, and must be 1 or more. |
NB40019 | 400 | The amount or fee is not accepted. | Check them against the minimums for the call. |
NB40020 | 400 | There isn't enough balance. | Top up the account or lower the amount. |
NB40021 | 400 | The card has reached its limit. | Contact NAS if the limit needs to be raised. |
NB40022 | 400 | The card's current status does not allow this. | Check the card's status, and change it first if that is allowed. |
NB40023 | 400 | The address is flagged as high risk. | Use a different address. |
NB40024 | 400 | The payment details are not valid. | Check the payee name, address, bank and branch codes and postal code. |
NB40025 | 400 | The exchange rate can no longer be used. | Request a new rate. |
NB40320 | 403 | This isn't permitted for this account or resource. | Check that you are using your own ids. |
NB40321 | 403 | The account can't be used for this operation, for example a type that cannot hold cardholders or cards. | Check the account and the call. Contact NAS if the account needs a different setup. |
NB40322 | 403 | The account is not active. | Contact NAS. |
NB40323 | 403 | The card has an outstanding balance. | Contact NAS to settle it before using the card again. |
NB40402 | 404 | The card was not found. | Check the card id and that the card belongs to your account. |
NB40410 | 404 | Something named in the request was not found, for example the cardholder. The message names it. | Check the ids you sent. |
NB40903 | 409 | Another request for the same thing is in progress. | Wait a moment, then repeat it with the same idempotency key. |
NB40904 | 409 | A user with these details already exists. | Look the user up instead of creating it again. |
NB42903 | 429 | Requests are arriving too quickly. | Wait a few seconds, then repeat the request. |
NB40099 | 4xx | Card processing refused the request for a reason not listed here. | Check the request against the API reference. If it looks right, contact NAS with the time and path. |
NB50002 | 500 | The card service could not complete the call. | Retry with the same idempotency key. If it keeps failing, contact NAS. |
NB50210 | 502 | The card service answered in a form NAS could not use. | Read the resource before repeating a call that creates something. |
NB50303 | 503 | The card service is temporarily unavailable. | Retry with the same idempotency key after a short wait. |
NB50305 | 503 | NAS needs to take an action before this can complete. | Retry with the same idempotency key. If it still fails after an hour, contact NAS. |
NB50299 | 5xx | Card processing failed for a reason not listed here. | Retry later with the same idempotency key. |
Retry or fix
| Situation | Retry? |
|---|---|
429 | Yes, after Retry-After. The call was not forwarded, so it is safe to repeat as it was. |
502 with NB50201 | Only after you have read the resource. The call may have succeeded. |
503 | Yes, with backoff, using the same idempotency key. |
| Network timeout, no answer | Yes, with the same idempotency key or referenceId. The original result comes back. |
400, 401, 403, 404 | No. Fix the cause first. The one exception is NB40102: refresh and retry once. |
When you get NB50201
The call reached card processing. NAS then held back the answer. Do not repeat a create blindly. First look the resource up by the id you chose: List cards with your referenceId, List cardholders, or List transactions with your clientTransactionId. If it exists, carry on. If it does not, repeat the call with the same idempotency key.
Keep for support
When you contact NAS, send the code, the message, the time, the HTTP status and the path. Never send access tokens, webhook secrets, card numbers or PINs.