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

low-balance

Details:

This request could not be performed due to your account balance being low.

Resolution:

Top up your account

Contact Support

unauthorized

Details:

You did not provide correct credentials.

Resolution:

Check your authentication credentials are correct, you can find these credentials in the Chatti Dashboard

Contact Support

forbidden

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

not-found

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

unprovisioned

Details:

The crendentials provided do not have access to the requested product

Resolution:

Check your API key is correct and has been whitelisted

account-suspended

Details:

This account has been suspended

Resolution:

Contact Support for more information

Contact Support

jwt-expired

Details:

The JWT provided has expired

Resolution:

Generate a new JWT with an exp in the future

jwt-revoked

Details:

The JWT provided has been revoked

Resolution:

Generate a new JWT using your private key

invalid-api-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

invalid-signature

Details:

The signature provided did not validate.

Resolution:

Check your signature secret is correct and you're following the correct signing process

See signing docs

invalid-ip

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

multiple-auth-methods

Details:

Multiple authentication methods were detected in your request

Resolution:

Provide exactly one authentication method

invalid-id

Details:

The ID provided does not exist in our system

Resolution:

Modify your request to provide a valid ID

invalid-json

Details:

The request body did not contain valid JSON

Resolution:

Send a JSON request body, including a Content-Type header of application/json

wrong-verb

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

Contact Support

accept-header

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

Contact Support

content-type-header

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

Contact Support

unavailable-legal

Details:

Unavailable For Legal Reasons

Resolution:

Vonage APIs are unavailable in the following areas due to international sanctions

  • Sudan

  • Syria

  • Crimea

  • North Korea

  • Iran

  • Cuba

application-suspended

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

1

Details:

Throttled. You are sending SMS faster than the account limit.

Contact Support

2

Details:

Missing Parameters. Your request is missing one of the required parameters from, to, api_key, api_secret or text.

Resolution:

Check your parameters and try again.

3

Details:

Invalid Parameters. The value of one or more parameters is invalid.

Resolution:

Check your parameters and try again.

4

Details:

Invalid Credentials. Your API key and/or secret are incorrect, invalid or disabled.

Contact Support

5

Details:

Internal Error. An error has occurred in the platform whilst processing this message.

Resolution:

If the error persists, Contact Support.

6

Details:

Invalid Message. The platform was unable to process this message, for example, an un-recognized number prefix.

Resolution:

N/A

7

Details:

Number Barred. The number you are trying to send messages to is blacklisted and may not receive them.

Resolution:

N/A

8

Details:

Partner Account Barred. Your Vonage account has been suspended.

Resolution:

Contact Support

9

Details:

Partner Quota Violation. You do not have sufficient credit to send the message.

Resolution:

Top-up and retry.

10

Details:

Too Many Existing Binds. The number of simultaneous connections to the platform exceeds your account allocation.

Resolution:

Back-off and retry.

11

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.

12

Details:

Message Too Long. The message length exceeds the maximum allowed.

Resolution:

Send shorter messages.

14

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.

15

Details:

Invalid Sender Address. You are using a non-authorized sender ID in the from field.

Resolution:

This is most commonly seen in North America, where a Vonage long virtual number or short code is required.

22

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.

23

Details:

Invalid Callback Url. The callback URL supplied was either too long or contained illegal characters.

Resolution:

Supply a valid URL for the callback.

29

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.

32

Details:

Signature And API Secret Disallowed. A signed request may not also present an api_secret.

Resolution:

Remove the API secret from your request, or don't sign the message.

33

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

invalid-product

Details:

The provided product is invalid

Resolution:

Modify your request to provide a valid product

View API reference

premature-redaction

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

rate-limit

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

validation

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

delete-last-secret

Details:

You can not delete your only API secret

Resolution:

Add another API secret before deleting this one

Subaccount API

Error ID

Information

Actions

validation

Details:

The request failed due to validation errors

Resolution:

See the detail (and, if present, the invalid_parameters) fields for the exact reason this request was rejected and review the documentation.

View API reference

valid-transfers

Details:

Invalid transfer

Resolution:

See the detail field for the reason this transfer is invalid.

View API reference

provisioning

Details:

Maximum number of sub-accounts reached

Resolution:

If you need more subaccounts, contact Vonage Support.

internal-error

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

payload-validation

Details:

Invalid request. See invalid_parameters field for details

Resolution:

Review the documentation and send a valid POST request.

View API reference

list-validation

Details:

Invalid request. See invalid_parameters field for details

Resolution:

Review the documentation and send a valid GET request.

View API reference

rate-limit

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

1000

Details:

Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry

1010

Details:

Missing params - Your request is incomplete and missing some mandatory parameters.

1020

Details:

Invalid params - The value of one or more parameters is invalid.

1021

Details:

Invalid tag - The tag value is invalid.

1022

Details:

Invalid template - Invalid template or template parameters

1030

Details:

Internal error - There was an error processing your request in the Platform.

1040

Details:

Invalid message - The Platform was unable to process your request. For example, due to an unrecognised prefix for the phone number.

1050

Details:

Number barred - The number you are trying to submit to is blacklisted and may not receive messages.

1060

Details:

Partner account barred - The api_key you supplied is for an account that has been barred from submitting messages.

1070

Details:

Partner quota exceeded - Your pre-paid account does not have sufficient credit to process this message.

1080

Details:

Account not enabled for REST - This account is not provisioned for REST submission, you should use SMPP on the SMS API.

1090

Details:

Message too long - The length of udh and body was greater than 140 octets for a binary type SMS request.

1100

Details:

Communication Failed - Message was not submitted because there was a communication failure.

1120

Details:

Illegal Sender Address - rejected - Due to local regulations, the SenderID you set in from in the request was not accepted. Please check the Global messaging section.

1130

Details:

Invalid TTL - The value of ttl in your request was invalid.

1140

Details:

Facility not allowed - Your request makes use of a facility that is not enabled on your account.

1150

Details:

Invalid Message class - The value of message-class in your request was out of range. See https://en.wikipedia.org/wiki/Data_Coding_Scheme.

1160

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.

1170

Details:

Invalid or Missing Param - The phone number you supplied in the to parameter of your request was either missing or invalid.

1180

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.

1190

Details:

Absent Subscriber Permanent - to is no longer active, You should remove this phone number from your database.

1200

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.

1210

Details:

Anti-Spam Rejection - Carriers often apply restrictions that block messages following different criteria. For example on SenderID or message content.

1220

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.

1230

Details:

Network Error - A network failure while sending your message. This is a temporary failure, retry later for a positive result.

1240

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.

1241

Details:

Too many send requests - Too many send requests to phone numbers.

1250

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

1260

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.

1270

Details:

Subscriber Age Restriction - The carrier blocked this message because the content is not suitable for to based on age restrictions.

1280

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.

1290

Details:

Pre-Paid - Insufficient funds - to’s pre-paid account does not have enough credit to receive the message.

1300

Details:

Not part of the provider network - The number or ID is not a user in the provider network.

1310

Details:

Not suitable device - The user's device can't receive the message.

1320

Details:

Message already sent - The message was already sent.

1330

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.

1331

Details:

Provider error - The provider is not responding or unable to process the request. Please try sending your message in a few minutes time.

1340

Details:

Outside of the allowed window - This message is sent outside of allowed response window.

1350

Details:

Phone matching fee not paid - Requires phone matching access fee to be paid by the Facebook Page.

1360

Details:

TTL was activated - TTL was activated, no callbacks and no charge will be issued.

1370

Details:

Expired access Token - Please reauthenticate your Facebook Page with Vonage.

1380

Details:

Invalid resource - Please check that the URL your provided to your resrouce is accesible and valid.

1381

Details:

Resource size is too large - Please try sending a smaller media file.

1382

Details:

Resource type is invalid - Please check that the file you are trying to send is valid.

Reports API

Error ID

Information

Actions

invalid-request-parameters

Details:

The provided payload is invalid

Resolution:

Modify your request to provide a valid payload

View API reference

invalid-abort-operation

Details:

The job is already in a terminated state such as SUCCESS, TRUNCATED, FAILED or ABORTED.

Resolution:

None

View API reference

WhatsApp Provisioning

Error ID

Information

Actions

number-in-use

Details:

Cannot use number because it's already in use by another deployment.

Resolution:

Use the existing deployment.

invalid-json

Details:

The request body did not contain valid JSON

Resolution:

Send a JSON request body, including a Content-Type header of application/json

unprocessable

Details:

Parameters were valid JSON but something was missing or wrongly formatted

Resolution:

Fix the incorrect request parameters and try again

unprocessable-profile-update

Details:

Parameters were valid JSON but something was missing or wrongly formatted

Resolution:

Fix the incorrect request parameters and try again

throttled

Details:

Too many requests have been made on this endpoint

Resolution:

Wait a moment and try again

verification-failed

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

conflict-deployment-state

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 DELETING, no action is required as the deployment will be deleted. Otherwise, wait for the transition to complete and try again.

conflict-resend-otp

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

Did this answer your question?