When a API returns an error, for instance, if your account has no credit, the API will return an error in RFC 7807 format.
This provides a basic explanation of what the issue is, why it occurred and steps to resolve it. Check out the example to see how an out-of-credit is formatted.
You'll likely want to consider up-front what errors your application will need to handle, this page provides a list of all the possible errors that could occur with a more detailed explanation of how they can be addressed.
Generic Errors
Error ID | Information | Actions |
| Details:
This request could not be performed due to your account balance being low.
Resolution: Top up your account | |
| Details:
You did not provide correct credentials.
Resolution: Check your authentication credentials are correct, you can find these credentials in the Chatti Dashboard | |
| Details:
Your account does not have permission to perform this action
Resolution: Check that you're using the correct credentials, and that your account has this feature enabled |
|
| Details:
The requested resource does not exist, or you do not have access to it
Resolution: Check both the URI that you're requesting and your authentication credentials |
|
| Details:
The crendentials provided do not have access to the requested product
Resolution: Check your API key is correct and has been whitelisted |
|
| Details:
This account has been suspended
Resolution: Contact Support for more information | |
| Details:
The JWT provided has expired
Resolution: Generate a new JWT with an |
|
| Details:
The JWT provided has been revoked
Resolution: Generate a new JWT using your private key |
|
| Details:
The API key provided does not exist in our system, or you do not have access
Resolution: Modify your request to provide a valid API key |
|
| Details:
The signature provided did not validate.
Resolution: Check your signature secret is correct and you're following the correct signing process | |
| Details:
The source IP address of the request is not in our allow list
Resolution: Make a request from an allowed IP address, or add your current IP to the list of authorized addresses |
|
| Details:
Multiple authentication methods were detected in your request
Resolution: Provide exactly one authentication method |
|
| Details:
The ID provided does not exist in our system
Resolution: Modify your request to provide a valid ID |
|
| Details:
The request body did not contain valid JSON
Resolution: Send a JSON request body, including a Content-Type header of application/json |
|
| Details:
This endpoint does not support the HTTP verb that you requested
Resolution: Read the API documentation to see which verbs your desired endpoint supports | |
| Details:
Invalid Accept header provided
Resolution: Most Vonage APIs only send back application/json. Check the API documentation for the API that you're working with for a complete list of supported data types | |
| Details:
Invalid Content-Type header provided
Resolution: Most Vonage APIs only accept application/json. Check the API documentation for the API that you're working with for a complete list of supported data types | |
| Details:
Unavailable For Legal Reasons
Resolution: Vonage APIs are unavailable in the following areas due to international sanctions
|
|
| Details:
This application has been suspended
Resolution: Re-enable the application or create a new application to use |
|
Product Specific Errors
SMS API
Error ID | Information | Actions |
| Details:
Throttled. You are sending SMS faster than the account limit.
| |
| Details:
Missing Parameters. Your request is missing one of the required parameters
Resolution: Check your parameters and try again. |
|
| Details:
Invalid Parameters. The value of one or more parameters is invalid.
Resolution: Check your parameters and try again. |
|
| Details:
Invalid Credentials. Your API key and/or secret are incorrect, invalid or disabled.
| |
| Details:
Internal Error. An error has occurred in the platform whilst processing this message.
Resolution: If the error persists, Contact Support. |
|
| Details:
Invalid Message. The platform was unable to process this message, for example, an un-recognized number prefix.
Resolution: N/A |
|
| Details:
Number Barred. The number you are trying to send messages to is blacklisted and may not receive them.
Resolution: N/A |
|
| Details:
Partner Account Barred. Your Vonage account has been suspended.
Resolution: |
|
| Details:
Partner Quota Violation. You do not have sufficient credit to send the message.
Resolution: Top-up and retry. |
|
| Details:
Too Many Existing Binds. The number of simultaneous connections to the platform exceeds your account allocation.
Resolution: Back-off and retry. |
|
| Details:
Account Not Enabled For HTTP. This account is not provisioned for the SMS API.
Resolution: This error usually indicates that you should use SMPP instead. |
|
| Details:
Message Too Long. The message length exceeds the maximum allowed.
Resolution: Send shorter messages. |
|
| Details:
Invalid Signature. The signature supplied could not be verified.
Resolution: Check the documentation for signing messages or use one of the SDKs to handle the signing. |
|
| Details:
Invalid Sender Address. You are using a non-authorized sender ID in the
Resolution: This is most commonly seen in North America, where a Vonage long virtual number or short code is required. |
|
| Details:
Invalid Network Code. The network code supplied was either not recognized, or does not match the country of the destination address.
Resolution: Check the network code or remove it from your request. |
|
| Details:
Invalid Callback Url. The callback URL supplied was either too long or contained illegal characters.
Resolution: Supply a valid URL for the callback. |
|
| Details:
Non-Whitelisted Destination. Your Vonage account is still in demo mode. While in demo mode you must add target numbers to your whitelisted destination list.
Resolution: Top-up your account to remove this limitation. |
|
| Details:
Signature And API Secret Disallowed. A signed request may not also present an
Resolution: Remove the API secret from your request, or don't sign the message. |
|
| Details:
Number De-activated. The number you are trying to send messages to is de-activated and may not receive them.
Resolution: N/A |
|
Redact API
Error ID | Information | Actions |
| Details:
The provided product is invalid
Resolution: Modify your request to provide a valid product | View API reference |
| Details:
There is a 1 hour time period before data can be redacted to allow for all data to propagate through the Vonage system
Resolution: Wait until the data becomes valid for redaction |
|
| Details:
The request was rate limited
Resolution: The Redact API supports 170 requests per second. Slow down your request rate |
|
Account API
Error ID | Information | Actions |
| Details:
The provided payload is invalid
Resolution: Modify your request to provide a valid payload. * Minimum 8 characters * Maximum 25 characters * Minimum 1 lower case character * Minimum 1 upper case character * Minimum 1 digit | View API reference |
| Details:
You can not delete your only API secret
Resolution: Add another API secret before deleting this one |
|
Subaccount API
Error ID | Information | Actions |
| Details:
The request failed due to validation errors
Resolution: See the | |
| Details:
Invalid transfer
Resolution: See the | |
| Details:
Maximum number of sub-accounts reached
Resolution: If you need more subaccounts, contact Vonage Support. |
|
| Details:
An error has occurred in the platform while processing this request
Resolution: If the error persists, contact Vonage Support. |
|
Application API
Error ID | Information | Actions |
| Details:
Invalid request. See
Resolution: Review the documentation and send a valid | View API reference |
| Details:
Invalid request. See
Resolution: Review the documentation and send a valid | |
| Details:
The request was rate limited
Resolution: The Redact API supports 170 requests per second. Reduce the frequency of your requests. |
|
Messages API
Error ID | Information | Actions |
| Details:
Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry
|
|
| Details:
Missing params - Your request is incomplete and missing some mandatory parameters.
|
|
| Details:
Invalid params - The value of one or more parameters is invalid.
|
|
| Details:
Invalid tag - The tag value is invalid.
|
|
| Details:
Invalid template - Invalid template or template parameters
|
|
| Details:
Internal error - There was an error processing your request in the Platform.
|
|
| Details:
Invalid message - The Platform was unable to process your request. For example, due to an unrecognised prefix for the phone number.
|
|
| Details:
Number barred - The number you are trying to submit to is blacklisted and may not receive messages.
|
|
| Details:
Partner account barred - The
|
|
| Details:
Partner quota exceeded - Your pre-paid account does not have sufficient credit to process this message.
|
|
| Details:
Account not enabled for REST - This account is not provisioned for REST submission, you should use SMPP on the SMS API.
|
|
| Details:
Message too long - The length of
|
|
| Details:
Communication Failed - Message was not submitted because there was a communication failure.
|
|
| Details:
Illegal Sender Address - rejected - Due to local regulations, the
|
|
| Details:
Invalid TTL - The value of
|
|
| Details:
Facility not allowed - Your request makes use of a facility that is not enabled on your account.
|
|
| Details:
Invalid Message class - The value of
|
|
| Details:
Non White-listed Destination - The phone number you set in to is not in your pre-approved destination list. To send messages to this phone number, add it using Dashboard.
|
|
| Details:
Invalid or Missing Param - The phone number you supplied in the to parameter of your request was either missing or invalid.
|
|
| Details:
Absent Subscriber Temporary - This message was not delivered because to was temporarily unavailable. For example, the handset used for to was out of coverage or switched off. This is a temporary failure, retry later for a positive result.
|
|
| Details:
Absent Subscriber Permanent -
|
|
| Details:
Portability Error - There is an issue after the user has changed carrier for to. If the user wants to receive messages from you, they need to contact their carrier directly.
|
|
| Details:
Anti-Spam Rejection - Carriers often apply restrictions that block messages following different criteria. For example on SenderID or message content.
|
|
| Details:
Handset Busy - The handset associated with to was not available when this message was sent. If status is rejected, this is a temporary failure; retry later for a positive result. If status is submitted, this message has is in the retry scheme and will be resent until it expires in 24-48 hours.
|
|
| Details:
Network Error - A network failure while sending your message. This is a temporary failure, retry later for a positive result.
|
|
| Details:
Illegal Number - You tried to send a message to a blacklisted phone number. That is, the user has already sent a STOP opt-out message and no longer wishes to receive messages from you.
|
|
| Details:
Too many send requests - Too many send requests to phone numbers.
|
|
| Details:
Unrouteable - The chosen route to send your message is not available. This is because the phone number is either currently on an unsupported network or on a pre-paid or reseller account that could not receive a message sent by from. To resolve this issue Contact Support
|
|
| Details:
Destination unreachable - The message could not be delivered to the phone number. If using Viber Service Messages your account might not be enabled for this country.
|
|
| Details:
Subscriber Age Restriction - The carrier blocked this message because the content is not suitable for to based on age restrictions.
|
|
| Details:
Number Blocked by Carrier - The carrier blocked this message. This could be due to several reasons. For example, to's plan does not include SMS or the account is suspended.
|
|
| Details:
Pre-Paid - Insufficient funds - to’s pre-paid account does not have enough credit to receive the message.
|
|
| Details:
Not part of the provider network - The number or ID is not a user in the provider network.
|
|
| Details:
Not suitable device - The user's device can't receive the message.
|
|
| Details:
Message already sent - The message was already sent.
|
|
| Details:
Unknown - An unknown error was received from the carrier who tried to send this this message. Depending on the carrier, that to is unknown. When you see this error, and status is rejected, always check if to in your request was valid.
|
|
| Details:
Provider error - The provider is not responding or unable to process the request. Please try sending your message in a few minutes time.
|
|
| Details:
Outside of the allowed window - This message is sent outside of allowed response window.
|
|
| Details:
Phone matching fee not paid - Requires phone matching access fee to be paid by the Facebook Page.
|
|
| Details:
TTL was activated - TTL was activated, no callbacks and no charge will be issued.
|
|
| Details:
Expired access Token - Please reauthenticate your Facebook Page with Vonage.
|
|
| Details:
Invalid resource - Please check that the URL your provided to your resrouce is accesible and valid.
|
|
| Details:
Resource size is too large - Please try sending a smaller media file.
|
|
| Details:
Resource type is invalid - Please check that the file you are trying to send is valid.
|
|
Reports API
Error ID | Information | Actions |
| Details:
The provided payload is invalid
Resolution: Modify your request to provide a valid payload | |
| Details:
The job is already in a terminated state such as
Resolution: None |
WhatsApp Provisioning
Error ID | Information | Actions |
| Details:
Cannot use number because it's already in use by another deployment.
Resolution: Use the existing deployment. |
|
| Details:
The request body did not contain valid JSON
Resolution: Send a JSON request body, including a Content-Type header of application/json |
|
| Details:
Parameters were valid JSON but something was missing or wrongly formatted
Resolution: Fix the incorrect request parameters and try again |
|
| Details:
Parameters were valid JSON but something was missing or wrongly formatted
Resolution: Fix the incorrect request parameters and try again |
|
| Details:
Too many requests have been made on this endpoint
Resolution: Wait a moment and try again |
|
| Details:
Verification step failed. Either because the the provided code was incorrect or because too many attempts have been made
Resolution: Try again with the correct OTP, or call resend-otp |
|
| Details:
Deployment could not be modified because it is currently in a transitional state.
Resolution: If the deployment is transitioning into the state you want it in no action is required. If the state is |
|
| Details:
Could not resend OTP because the current state of the deployment did not allow it
Resolution: The deployment has either already finished, or is in an error state (in which case you should delete it and run it again). |
|