Instagram Messaging API error codes, explained one by one
Last verified against Meta for Developers - Messenger Platform error codes
Instagram messaging runs on the Graph API through two distinct routes, and the error surface is the same for both. The original route is the Messenger Platform: your app messages through a Facebook Page that is linked to the Instagram professional account, using a Page access token with instagram_manage_messages. Since July 2024 there is also the Instagram API with Instagram Login, which needs no Facebook Page and uses instagram_business_manage_messages-scoped tokens instead. A token from one route does not work against the other route's endpoints, and several errors below - notably (#10) and 100/2534013 - are really route mix-ups in disguise.
Two prerequisites fail silently, without any error code. The account must be a professional account (Business or Creator), and the account owner must switch on Allow access to messages under Settings > Messages and story replies > Message controls > Connected Tools in the Instagram app. When that toggle is off, Meta simply never generates webhook events for your app; when it is switched off later, sends start failing with 200/2534041. If nothing reaches your webhook at all, work through the Instagram messaging troubleshooting guide and the webhook debugging guide before assuming an API error.
Every failure comes back as a Graph API error object. code is the coarse family - 190 is always a token problem, 10 and 200 are permission-shaped, 100 is a parameter problem, 4/17/32/613 are throttling. error_subcode is where Instagram gets specific: the 2534xxx subcodes are Instagram-messaging-specific, so 10/2534022 (messaging window) and 10 without a subcode (missing permission) need entirely different fixes. Read both numbers before touching anything, keep fbtrace_id for Meta support, and check every numeric ceiling these errors enforce in the Instagram limits reference.
How to read a Instagram error
Errors are returned synchronously in the HTTP response body of the call you just made. The two integers to branch on are code and error_subcode:
{
"error": {
"message": "(#10) Message failed to send because more than 24 hours have passed since the customer last replied to this account.",
"type": "OAuthException",
"code": 10,
"error_subcode": 2534022,
"fbtrace_id": "A2mNpXvKeLqRbTw"
}
}The message combines the code in parentheses with a human-readable sentence; type is almost always OAuthException even for non-auth failures, so never branch on it. fbtrace_id identifies this exact request in Meta's logs - Direct Support cannot investigate without it, so log the whole object.
All 29 codes
Jump to: Access tokens & authentication (4) · Permissions & app review (2) · Messaging window (1) · Recipient & delivery (5) · Rate limits & throttling (4) · Media & attachments (3) · Account setup & connection (6) · Generic & request errors (4)
Access tokens & authentication
| Code | Title |
|---|---|
190 | Session has expired Error validating access token: Session has expired on {date}. The current time is {date}. |
190 | Session invalidated - password changed or session revoked Error validating access token: The session has been invalidated because the user changed their password or Facebook h… |
190 | Invalid OAuth access token Access Token Error: Invalid OAuth access token. |
190 | Access token expired, revoked, or invalid Access token has expired, been revoked, or is otherwise invalid. |
Permissions & app review
| Code | Title |
|---|---|
10 | Application does not have permission for this action (#10) Application does not have permission for this action |
200 | Permission error - app not live for this recipient Permission Error: Cannot message users who are not admins, developers or testers of the app until pages_messaging per… |
Messaging window
| Code | Title |
|---|---|
10 | Message sent outside of allowed window This message is sent outside of allowed window. |
Recipient & delivery
| Code | Title |
|---|---|
200 | This person isn't available right now Message Not Sent: This person isn't available right now. |
551 | This person isn't receiving messages from you right now User Block Error: This person isn't receiving messages from you right now. |
10 | This person cannot receive messages This Person Cannot Receive Messages: This person isn't receiving messages from you right now. |
100 | No matching Instagram user No matching Instagram user |
100 | Comment is invalid for a private reply The comment is invalid for a private reply |
Rate limits & throttling
| Code | Title |
|---|---|
4 | Application request limit reached (#4) Application request limit reached |
32 | Page request limit reached (#32) Page request limit reached |
17 | User request limit reached (#17) User request limit reached |
613 | Calls to this API have exceeded the rate limit Calls to this api have exceeded the rate limit. |
Media & attachments
| Code | Title |
|---|---|
100 | Failed to fetch the file from the URL Failed to fetch the file from the url. Check that the URL is valid, with a valid SSL certificate, valid file size, an… |
100 | Attachment size exceeds allowable limit Attachment size exceeds allowable limit |
100 | Video upload timed out or video is corrupted Video upload timed out or video is corrupted. Note that if the video can't be fetched within 75 seconds, it will time… |
Account setup & connection
| Code | Title |
|---|---|
200 | Account owner has disabled access to direct messages The account owner has disabled access to instagram direct messages. |
10 | Cannot verify connection between IG account, user and Page Cannot verify the connection between the IG account, the logged in user and the page. Please try reconnecting or veri… |
100 | Page is not linked to an Instagram account The page is not linked to an Instagram account |
100 | Business blocked from the Instagram Messaging API The business has been blocked from sending messages via the IG Messaging API |
100 | Action invalid - app is not the thread owner The action is invalid since it's not the thread owner. |
36103 | This IG account is not eligible for API yet This IG account is not eligible for API yet |
Generic & request errors
| Code | Title |
|---|---|
100 | Invalid parameter Bad Parameter Error: Invalid FBID. |
100 | Invalid message data Invalid message data |
1 | Unknown error An unknown error occurred. |
2 | Unexpected error - retry later An unexpected error has occurred. Please retry your request later. |
Instagram guides and tools
Other platforms
Frequently asked questions
Where do Instagram Messaging API errors appear?
Synchronously, in the HTTP response body of the Graph API call you just made, as an error object with message, type, code, error_subcode and fbtrace_id. Instagram has no equivalent of WhatsApp's failed-status webhook for most send errors, so if you do not log the response body of every send, failures vanish. Webhook problems are the opposite case: no error anywhere, just silence.
What does error code 10 with subcode 2534022 mean?
You replied outside the standard messaging window. Meta documents it as "This message is sent outside of allowed window" - apps may only message a person within 24 hours of that person's last message. It is not a permissions problem, even though the code is 10 and the type is OAuthException. Track the last inbound timestamp per conversation and stop automated sends when the window closes.
How is (#10) without a subcode different from (#10) with 2534022?
Bare (#10) "Application does not have permission for this action" means the token lacks instagram_manage_messages, or your app lacks Advanced Access for it. Subcode 2534022 means the permission is fine and you are simply outside the 24-hour window. The code alone is ambiguous; always read error_subcode and the message string before deciding which fix applies.
Why does my Instagram bot get error 190 after weeks of working?
The token died. Subcode 463 is plain expiry - usually a short-lived token or a missed refresh. Subcode 460 means the person who issued the token changed their password or was logged out. Page tokens derived from long-lived user tokens do not expire on a timer but are invalidated when that user loses Page access, deauthorizes the app, or changes credentials.
Which Instagram messaging errors are safe to retry?
Codes 1 and 2 (transient platform errors) with backoff, and the throttling family 4, 17, 32 and 613/2534040 after waiting for the window to reset. Do not blindly retry 10/2534022, 551, 200/1545041 or any 2534xxx configuration error - they fail identically until you change the underlying condition, and retries add to your rate-limit usage.
What are the 2534xxx error subcodes?
Instagram-specific subcodes on the Messenger Platform error page. They pin down what the generic code could not: 2534022 is the messaging window, 2534013 means the Page is not linked to an Instagram account, 2534014 is an invalid Instagram-scoped ID, 2534029 means the business is blocked from the messaging API, 2534040 is the messaging rate limit, and 2534041 means the account owner switched off message access.
Why do sends work for my account but fail with code 200 for real users?
Your app is in Development mode or the messaging permission only has Standard Access. Meta documents code 200 as being unable to message users who are not admins, developers or testers until the permission passes App Review and the app is live. Testers must accept an invitation; everyone else needs Advanced Access, which usually requires Business Verification.
Can I message a user after the 24-hour window on Instagram?
Only with the human_agent tag, which allows a human agent - not an automation - to reply within 7 days of the user's message, after your app is approved for the Human Agent feature. Instagram supports no other message tags: ACCOUNT_UPDATE, CONFIRMED_EVENT_UPDATE and CUSTOMER_FEEDBACK are documented as not available for the Instagram Messaging API, and there is no template mechanism like WhatsApp's.
What is fbtrace_id and why should I log it?
It is the trace identifier Meta attaches to every Graph API response. Meta support uses it to find the request in internal logs and cannot investigate a report without it. It is not recoverable later, so log the entire error object - message, code, error_subcode and fbtrace_id - not just the numeric code, for every failed send.
Why do I get no error at all - just silence?
The most common Instagram failures produce no error code. The Allow access to messages toggle being off, a missing Page-level webhook subscription, an app in Development mode receiving events only for app roles, and unaccepted tester invites all result in events never being generated. Silence is a configuration symptom; work through the connection checklist in /blog/instagram-messaging-api-not-working rather than waiting for a code.
Run your Instagram bot without babysitting error codes
Conferbot manages the connection, tokens, webhooks and retries, and shows failures as readable status.