Error Messages
On this page, we will list all the error messages you might encounter when calling our APIs, what they mean and how you can fix them. If any errors you receive that are not covered below, please reach out, and we will add them.
System health
You can use the following link to see our current service status: https://status.notabene.id/
General errors
Errors in the Notabene API follow conventional HTTP response codes to indicate errors. Generally, 2xx response codes indicate success, 4xx response codes indicate client error, and 5xx errors indicate errors with the Notabene API.
Success
200 - OK - The request was successfully handled
Client errors
400 - Bad Request - The API could not process the request due to an incorrect request
401 - Unauthorized - The user of the API was not authenticated
403 - Forbidden - The user of the API was not authorized to make the request
404 - Not found - The requested resource could not be found. Check that the correct method is used.
405 - Method not allowed
Notabene errors
500, 502, 503, 504 - Server Errors - Something went wrong with the Notabene API.
When this error is returned by our API we recommend building a queue and implementing a retry mechanism, ensuring you are using the transaction ref field as an idempotency key
| Error | Content | Why |
|---|---|---|
| Unauthorized | { "err": { "message": "unauthorized" } } | You are trying to make a call with the wrong token or no token at all. |
| Unhandled error | { "err": "Unhandled error. ('Unsupported message type')" } | Please check that the token is correct. |
| Method not allowed | { "err": { "message": "method not allowed" } } | |
| { "err": { "name": "Error", "message": "Identity not found" } } |
IVMS errors
| Error | Content | Why |
|---|---|---|
| originatorNameMissing | originator.....primaryIdentifier (should also include the secondary) "nameIdentifier": [ { "primaryIdentifier": "Stark", "secondaryIdentifier": "Brice" } ] | |
| originatorAccountNumberMissing | originator.....accountNumber "accountNumber": [ "3jwpzoHEKoK9XKMryXHBRLWKoibFMxfNmj" ] | |
| originatorGeographicAddressMissing | {"err":{"code":400,"message":"["originatorGeographicAddressMissing"]" ,"name":"TransactionError"}} | originator.....geographicAddress There must be at least one occurrence of the element addressLine or (streetName and buildingName and/or buildingNumber). "geographicAddress": [ { "streetName": "streetName", "buildingNumber": "buildingNumber", "country": "{{$randomCountryCode}}" } |
| originatorNationalIdentificationMissing | originator..... nationalIdentification "nationalIdentification": { "nationalIdentifier": "123456789", "nationalIdentifierType": "DRLC" | |
| originatorCustomerIdentificationMissing | originator..... customerIdentification "customerIdentification": "abcde12345" | |
| originatorDateAndPlaceOfBirthMissing | originator..... dateAndPlaceOfBirth "dateAndPlaceOfBirth": { "dateOfBirth": "1999-01-01", "placeOfBirth": "{{$randomCountryCode}}" | |
| beneficiaryNameMissing | beneficiary.....primaryIdentifier (should also include the secondary) "nameIdentifier": [ { "primaryIdentifier": "Stark", "secondaryIdentifier": "Brice" } ] | |
| beneficiaryAccountNumberMissing | beneficiary.....accountNumber | |
| beneficiaryGeographicAddressMissing | beneficiary.....geographicAddress There must be at least one occurrence of the element addressLine or (streetName and buildingName and/or buildingNumber). | |
| beneficiaryCountryOfResidenceMissing | beneficiary..... countryOfResidence | |
| beneficiaryOwnershipProofMissing | beneficiaryProof: type + proof |
Authentication
| Error | Content | Why |
|---|---|---|
| access_denied | { "error": "access_denied", "error_description": "Client is not authorized to access "[https://api.notabene.dev\](https://api.notabene.dev\) ". You need to create a "client-grant" associated to this API. See: https://auth0.com/docs/api/v2#!/Client_Grants/post_client_grants" } | |
| access_denied | { "error": "access_denied", "error_description": "Unauthorized" } | |
| access_denied | { "error": "access_denied", "error_description": "Service not enabled within domain: https://api.notabene ." } | |
| UnauthorizedError | { "error": "UnauthorizedError: jwt issuer invalid. expected: https://notabene-eu.eu.auth0.com/" } | This error should not occur anymore, if you get it please contact us. |
| UnauthorizedError | { "error": "UnauthorizedError: bad token" } | Your token is not correct, try copy-pasting again. |
| UnauthorizedError | { "error": "UnauthorizedError: jwt expired" } | Your token has expired, request a new one. |
txValidate/txValidateFull
| Error | Content | Why |
|---|---|---|
| CustomerDIDNotonVASPError | { "err": { "name": "CustomerDIDNotonVASPError", "code": 400, "message": "Customer did:ethr:0x5b2b0ff3217175d1bad5c9ad2a5a1d4bc96e6bc8 is not on VASP did:ethr:0xc8dcb6ef2f8c43b5caba0bd04a7faf201de86168" } } | This error happens most likely because you are using the wrong token. txValidate uses a customerToken. |
| PaymentError | ||
| TrustFrameworkVASPNotFoundError | { "err": { "name": "TrustFrameworkError", "code": 400, "message": "no VASP found with vaspDID: did:ethr:0x75215d5bfc19e1a4f0301b40abcfdddd6de8613" } } | The VASP DID that you have passed is not present in our directory. |
| TransactionError | ||
| UserDIDNotAdminforVASPError | ||
| PaymentNoCustomerError | ||
| PaymentNoSubscriptionError | ||
| TransactionNoActiveSubscriptionError | ||
| TransactionValidationError |
txCreate
| Error | Content | Why |
|---|---|---|
| TransactionError | { "err": { "name": "TransactionError", "code": 400, "message": "You only have $USD 10000 left in monthly transactions volume for this month. Contact Notabene to upgrade" } } | You are using an account that is under the sunrise plan. The sunrise plan is to enable anyone to be able to respond to travel rule messages, regardless of having a solution for it or not. This account type can receive unlimited incoming transactions, but only send up to 10k per month. Please reach out and we can convert your testing account to unlimited transactions. |
| UserDIDNotAdminforVASPError | The token used to make the request belongs to a USER that is not an Admin on the specific VASP. Make sure that the correct originator VASP DID or authentication token is being used. | |
| PaymentNoCustomerError | { "err": { "name": "NotabenePaymentNoCustomerError", "code": 400, "message": "did:ethr:0xa6e435a202d1b85baf09c1abe6bb8ee416b8f12e is not a customer (no customerID)" } } | |
| PaymentNoSubscriptionError | ||
| TransactionNoActiveSubscriptionError | ||
| TransactionValidationError | ||
| TransactionBelowThresholdError | ||
| TransactionSunriseLimitReachedError | The VASP has reached the 10K USD limit on outgoing transactions in the Sunrise plan. Get in touch to convert your dev account to unlimited. | |
| User … not a user of … | { "err": { "name": "Error", "message": "User "did:ethr:0xefbb14b73473ccfd610543af4b1c8fda027c57bf" not a user of "did:ethr:0xf963d5607d7895d7fcb167e5b742ae2e2b8e9b2d"" } } | You are trying to send a request on behalf of a VASP DID that you do not have access to. Either make sure you are using the right token or change the originating VASP DID. |
txUpdate
| Error | Content | Why |
|---|---|---|
| Identity not found | { "err": { "name": "Error", "message": "Identity not found" } } | |
| TransactionError | { "err": { "name": "TransactionError", "code": 400, "message": "'SENT' is not a valid status for 'txUpdate'. you can only update originator Data when status is INCOMPLETE or MISSING_BENEFICIARY_DATA" } } | Once the transaction has been sent or actioned by the beneficiary VASP, you cannot change the content of it. |
txConfirm
| Error | Content | Why |
|---|---|---|
| TransactionError | {"err":{"name":"TransactionError","code":400,"message":"undefined was not found."}} | Your request is not formatted correctly, make sure that the data is passed in the URL. |
| TransactionError | { "err": { "name": "TransactionError", "code": 400, "message": "123e4567-e89b-12d3-a456-426614174000 was not found." } } | The ID you added is not found in your inbox, check that it is correct. |
| TransactionError | { "err": { "name": "TransactionError", "code": 400, "message": "'ACK' is not a valid status for 'confirm'. " } } | Please see the travel rule status diagram to see which call is applicable for each status. |
Javascript SDK connection error
Service Unavailable
Type: SERVICE_UNAVAILABLE
Description: The Notabene service is currently unavailable due to backend issues.
Resolution: Retry the request later. If the issue persists, contact support.
Wallet Connection Failed
Type: WALLET_CONNECTION_FAILED
Description: The connection to the wallet service failed, possibly due to network issues or unsupported wallet types.
Resolution: Verify the wallet is online and compatible with the current operation.
Wallet Not Supported
Type: WALLET_NOT_SUPPORTED
Description: The wallet used does not support the required functionality or blockchain.
Resolution: Use a compatible wallet that supports the necessary features.
Updated 5 days ago