The following table contains a list of common error codes you may encounter when using the Messenger Platform.
{ "error": { "message": "Invalid OAuth access token.", "type": "OAuthException", "code": 190, "error_subcode": 1234567, "fbtrace_id": "BLBz/WZt8dN" } }
Code – Subcode | Message | Possible Solution |
---|---|---|
| An unknown error occurred. | Missing permissions can cause this issue. |
| Received invalid JSON reply. | The developer is sending a batch of messages containing 2 text messages and 1 video. The messages are all sent successfully, but the endpoint returns an error. Is the object that they are sending causing the problem? There is a system delay in returning the error message. |
| An unexpected error has occurred. Please retry your request later. | When experiencing issues making calls to the Meta social graph, you can check the status of the Meta Developer Platform to determine if there are issues affecting API calls. You might also receive this error if a customer has blocked your business from messaging him or her. |
| Service temporarily unavailable Privacy ToS not accepted – To use the inbox label API, you need to accept the privacy ToS. Click the link to accept. https://www.facebook.com/100841475479486/inbox/page_contact_tos/ | The Page admin must accept the Privacy Terms of Service for Custom Labels. |
| Rate Limit error: Application request limit reached. Rate Limit error: Too many send requests to phone numbers | Pause requests until current requests drop below the limit. |
| Marketing Messages – There has to be a minimum delay between 2 notifications for the given notification | When a Marketing Message bypasses the frequency set in the This error code will not cause your app to be flagged or blocked for abuse. It is okay to ignore this error, but ideally you should keep track of which users you have sent messages to per the agreed cadence, so you can exclude those users from the next batch of broadcast messages. |
| User is performing too many actions | When the Marketing Message opt–in request limit has been exceeded. |
| No Permission For Pages Associated to Instant Games. | The User Profile API is not available for PSIDs associated with Instant Game Pages. |
| Application does not have permission for this action | When the Page is temporarily restricted from sending Marketing Message opt–in requests. |
| (#10) This user has currently stopped notification messages for this topic | When the Page sends a Marketing Message after the user clicks "Stop these messages". |
| User Thread Impact | To determine whether there is user thread impact, invoke the User Level Menu API. If you get a valid response, there is no impact. If you get an error message with code 10, subcode 2018336, the thread is impacted. |
| This message is sent outside of allowed window. | Apps can only send a message to a customer within 24 hours of receiving the customer's message. |
| Cannot verify the connection between the IG account, the logged in user and the page. Please try reconnecting or verify if the user needs 2–factor authentication. | The page and IG account are not linked or 2–factor authentication is not enabled. Add a link to the 2–factor authentication document (It might be in the help center). Advise the user to check the linkage and perhaps link and unlink the page and the IG account to fix the issue. |
| This message is sent outside of allowed window. Learn more about the new policy here. | |
| This message is sent outside of allowed window. You need News Messaging permission to be able to do it. | |
| This Person Cannot Receive Messages: This person isn't receiving messages from you right now. | |
| Bad Parameter Error: Invalid FBID. Bad Parameter Error: No matching user found.
| Check to make sure the ID or token you are using is valid. |
| Unsupported get request. Object with ID * does not exist, cannot be loaded due to missing permissions, or does not support this operation. | Make sure the ID in your request exists and that your app has the proper permissions to access it. |
| No matching user found | |
| Failed to fetch the file from the url. Check that the URL is valid, with a valid SSL certificate, valid file size, and that the server is responding fast enough to avoid timeouts. | |
| Cannot send both message and state at the same time. | |
| Upload attachment failure. A common way to trigger this error is that the provided media type does not match type of file provided int the URL. | |
| Possible invalid ID or you do not own the attachment. | Please view Document Source: Attachment Upload API |
| Attachment size exceeds allowable limit | |
| Incorrect App ID. | |
| Video upload timed out or video is corrupted. Note that if the video can't be fetched within 75 seconds, it will time out. | |
| Invalid product id | Check to make sure the product ID you are using in your Product Template is a valid ID and that your app has permission to access it. |
| Product template is not supported below version 8. Use API version 8 or higher to use product templates. | |
| The page is not linked to an Instagram account | The Page ID used in your API calls must be for the Facebook Page linked to your Instagram Professional account. |
| No matching Instagram user | Check to make sure the ID you are using is a valid Instagram–scoped ID. Instagram User ID are not supported. |
| Invalid message data | Make sure that the type of data you are sending in your message is allowed for your message type. |
| The comment is invalid for a private reply | Make sure that the type of data you are sending in your private reply is allowed. |
| The business has been blocked from sending messages via the IG Messaging API | Check to make sure you do not have any policy violations that must be rectified before you can send messages using the Messenger Platform. |
| The action is invalid since it's not the thread owner. | You do not have permission to perform the action on this conversation. Check that your app has the correct permissions and access tokens to manage the conversation. |
| Access Token Error: Invalid OAuth access token. | |
| Permission Error: Cannot message users who are not admins, developers or testers of the app until pages_messaging permission is reviewed and the app is live. | |
| Message Not Sent: This person isn't available right now. | |
| Requires phone matching access fee to be paid by this page unless the recipient user is an admin, developer, or tester of the app. | |
| Cannot message users who are not admins, developers or testers of the app until pages_messaging_phone_number permission is reviewed and the app is live. | |
| Cannot message users who are not admins, developers or testers of the app until pages_messaging permission is reviewed and the app is live. | |
| The account owner has disabled access to instagram direct messages. | The owner of the Instagram Professional account has revoked your app's access. |
| User Block Error: This person isn't receiving messages from you right now. | |
| This person isn't available right now. | |
| Scope of service exceeded: You may not send multiple opt–in requests with the same topic to a user. | When a Page sends more than 1 opt–in request to the user on the same topic. If a user receives this type of error through opting–in via Send to Messenger, you will need to inform the user on your website that an opt–in request was already sent to Messenger |
| Warning! You are engaging in behavior that may be considered bothersome or abusive by users. You must significantly decrease the rate at which you are sending messages using message tags to this person. Further misuse of API features may result in messaging restrictions being placed on your Page | |
| Calls to this api have exceeded the rate limit. | Your app has reached the rate limit. Pause API calls and try again later. |
| The ability to send commerce messages has been temporarily disabled. This is the result of a feature limit placed after a policy violation. | |
| Account Linking Error: Invalid account_linking_token. | |
| User canceled payment flow | |
| Payment request cannot be processed due to missing privacy url | |
| Failed to get user ID | |
| To onboard creator accounts during Instagram phased rollout | Call the Conversation API with the page access token to check their eligibility: if the API responds with error code |
| Could not send Instant Game message to the user at this time, only 5 notifications can be sent to a user within 10 days since they last played. | Pause your requests until the number of requests falls below the limit. |
| Messenger Extensions unexpected error | |
| Begin Share Param Validation Error | |
| Permission not valid to call the SDK API | |
| Only available to Primary and Secondary Receivers. | |
| No profile available for this user. | Currently, the User Profile API does not support retrieving profile information for Messenger accounts that were created using a phone number. Please check Source Document: User Profile –– Profile Info (User Profile API) |
| Denying visibility of any secondary receiver to another secondary receiver other than itself. | |
| Insufficient permission to access user profile. | The app calling the User Profile API has not been granted the permissions needed to access one or more of the requested fields. For more information, see Available Profile Filelds. |
| Message failed to send because another app is controlling this thread now. | |
| The chat is currently controlled by Messenger while the user is in an automated question and answer flow. Please wait for the flow to finish before trying again. | |
| This SDK method is not supported on this Messenger client. Please upgrade | |
| Messenger Extensions are not enabled – could be "messenger_extensions" was not set on a url, the domain was not added to the allow list or this is an outdated version of Messenger client | |
| Invalid MessageContent provided to SDK API call | |
| Invalid title string provided in message content | |
| Invalid subtitle string provided in message content | |
| Invalid image URL provided in message content | |
| Invalid item URL provided in message content | |
| Invalid button data provided in message content | |
| URL data is missing in message content. Please provide item_url, button_url or both | |
| sharingType provided in beginShareFlow call is not valid | |
| Invalid attachment in begin share flow message content | |
| Attachment type in message content must be set to template | |
| Payload is not valid in message content attachment | |
| Invalid open graph url provided in message content | |
| This Message has been deleted by the user or the business. | OAuthException |
Handling Errors Requests made to our APIs can result in several different error responses. There are different recovery tactics. The document provides a list of error values with a map to the most common recovery tactic to use.
Rate Limits A rate limit is the number of API calls an app or user can make within a given time period. If this limit is exceeded or if CPU or total time limits are exceeded, the app or user may be throttled. API requests made by a throttled user or app will fail.