Cloud API Error Codes
This topic contains the list of cloud API error codes, you can refer to them if you are using embedded signed-up
The Cloud API WhatsApp Error Codes are categorized in the following section:
|AuthException||Meta is unable to authenticate the application user.||The common reason for the error is either the access token has expired, the access token has been invalidated, or the application user has changed a setting to prevent all applications from accessing their data. We recommend that you get a new access token from the application user.|
|API Method||Capability or permissions issue.||Use the access token debugger to verify that your application has been granted the permissions required by the endpoint.|
|Permission Denied||Permission is either not granted or has been removed.||Use the access token debugger to verify that your application has been granted the permissions required by the endpoint.|
|Access token has expired||Your access token has expired.||Get a new access token.|
|API Permission||Permission is either not granted or has been removed.||Use the access token debugger to verify that your application has been granted the permissions required by the endpoint.|
|API Too Many Calls||The application has reached its API call rate limit.||Load the application in the application Dashboard and view the Application Rate Limit section to verify that the application has reached its rate limit. In this case, try again later or reduce the frequency or amount of API queries the application makes.|
|Rate limit issues||The WhatsApp Business Account has reached its application rate limit.||See WhatsApp Business Account Rate Limits. Try again later or reduce the frequency or amount of API queries the app is making.|
|Rate limit hit||Cloud API message throughput has been reached.||The application has reached the API's throughput limit. Try again later or reduce the frequency with which the app sends messages.|
|Spam rate limit hit||Message failed to send because there are restrictions on how many messages can be sent from this phone number. This may be because too many previous messages were blocked or flagged as spam.||Check your quality status in the WhatsApp Manager.|
|(Business Account and Consumer Account) pair rate limit hit||Too many messages are sent from the sender's phone number to the same recipient's phone number in a short period.||Wait and retry the operation, if you intend to send messages to the same phone number. You can still send messages to a different phone number without waiting.|
|Temporarily blocked for policies violations||The WhatsApp Business Account associated with the application has been restricted or disabled for violating a platform policy.||For more information contact the Kaleyra Support team.|
|Account has been locked||The WhatsApp Business Account associated with the application has been restricted or disabled for violating a platform policy.|
Meta is unable to verify data included in the request against the data set on the WhatsApp Business Account. For example, the two-step pin included in the request is incorrect.
|For more information contact the Kaleyra Support team.|
|API Unknown||Invalid request or server error.||In the Kaleyra.io application, check the WhatsApp Business Platform Status page to view API status information. If there are no server outages, check the endpoint reference and verify that your request is formatted correctly and meets all endpoint requirements.|
|API Service||Temporary due to downtime or due to being overloaded.||In the Kaleyra.io application, check the WhatsApp Business Platform Status page to view API status information before trying again.|
|Parameter is invalid||The request included one or more unsupported or misspelled parameters.||See the endpoint's reference to determine which parameters are supported.|
|Something went wrong||The message failed to send due to an unknown error.||Try again. If the error persists, create a Direct Support ticket with Kaleyra.|
|Access denied||Permission is either not granted or has been removed.||Use the access token debugger to verify that your application has been granted the permissions required by the endpoint.|
|Required parameter is missing||The request is missing a required parameter.||See the endpoint's reference to determine which parameters are required.|
|Parameter value is not valid||One or more parameter values are unsupported, the recipient phone number is not a valid WhatsApp phone number, or the sender phone number has not been added to the WhatsApp Business Platform.||See the endpoint's reference to determine which values are supported for each parameter.|
To learn how to add a phone number to a WhatsApp Business Account, see Add WhatsApp Number.
|Service unavailable||Service is temporarily unavailable.||To see API status information, check the WhatsApp Business Platform Status page before trying again.|
|Recipient cannot be sender||The sender's and recipient's phone number is the same.||Send a message to a phone number that is different from the sender.|
|Recipient cannot receive message||The recipient is using a version of WhatsApp that does not support the message's contents.||Advise the recipient to update to the latest version of WhatsApp.|
|Business eligibility - Payment issue||Message failed to send because there were one or more errors related to your payment method.||See About Billing For Your WhatsApp Business Account and verify that you have set up billing correctly.|
1. Payment account is not attached to a WhatsApp Business Account.
2. Credit line is over the limit.
3. Credit line (Payment Account) not set or active.
4. WhatsApp Business Account is deleted.
5. WhatsApp Business Account is suspended.
6. Timezone not set.
7. Currency not set.
8. MessagingFor request (On Behalf Of) is pending or declined.
9. Exceeded conversation free tier threshold without a valid payment method.
|Incorrect certificate||The message failed to send due to a phone number registration error.||Register the phone number before trying again.|
|Re-engagement message||More than 24 hours have passed since the recipient last replied to the sender's number.||Send the recipient a business-initiated message using a message template instead.|
|Unsupported message type||Unsupported message type.||See Messages for supported message types before trying again with a supported message type.|
|Media download error||The media type sent by the WhatsApp user is not supported.||See Supported Media Types. Check the details value for additional information and advise the user to resend the message using a supported format.|
|Media upload error||The media type sent to the WhatsApp user is not supported.||Check Supported Media Types. Also, check the details value for additional information and try again using a media format that is supported.|
|Template Param Count Mismatch||The number of variable parameter values included in the request did not match the number of variable parameters defined in the template.||See Message Template Guidelines and make sure the request includes all of the variable parameter values that have been defined in the template.|
|Template does not exist||The template does not exist in the specified language or the template has not been approved.||Make sure your template has been approved and the template name and language locale are correct. Please ensure you follow message template guidelines.|
|Template Hydrated Text Too Long||The translated text is too long.||Check the WhatsApp Manager to verify that your template has been translated.|
|Template Format Character Policy Violated||Template content violates a WhatsApp policy.||See Rejection Reasons to determine possible reasons for violation.|
|Template Parameter Format Mismatch||Variable parameter values are formatted incorrectly.||The variable parameter values included in the request are not using the format specified in the template.|
|Template parameter invalid||Template parameters are invalid or missing.||Make sure you follow message template guidelines. Verify the following:|
you are providing the right parameter count
the template exists and is approved
the template’s name and language locale are correct
the template has been translated correctly.
|Incomplete Deregistration||A previous deregistration attempt failed.||Deregister the number again before registering.|
|Server Temporarily Unavailable||The server is temporarily unavailable.||Check the WhatsApp Business Platform Status page to see API status information and check the response details value before trying again.|
|Two step verification PIN Mismatch||Two-step verification PIN incorrect.||Verify that the two-step verification PIN included in the request is correct.|
To reset the two-step verification PIN:
Disable two-step authorization.
Send a POST request that includes the new PIN to the Phone Number endpoint.
|Phone number re-verification needed||The phone number needs to be verified before registering.||Verify the phone number before registering it.|
|Too Many two step verification PIN Guesses||Too many two-step verification PIN guesses for this phone number.||Try again after the amount of time specified in the detailed response value.|
|Two step verification PIN Guessed Too Fast||Two-step verification PIN was entered too quickly.||Check the detailed response value before trying again.|
|Phone number Not Registered||Phone number is not registered on the Whatsapp Business Platform.||Register the phone number before trying again.|
|Generic user error||The message failed to send because of an unknown error with your request parameters.||See the endpoint's reference to determine if you are querying the endpoint using the correct syntax. Contact customer support if you continue receiving this error code in response.|
Updated 5 months ago