Instagram Messaging API · error code

Instagram error 17: User request limit reached

RetryableHTTP 400Rate limits & throttling

Last verified against Meta for Developers - Messenger Platform error codes

What Instagram returns
(#17) User request limit reached

What error 17 means

Code 17 is user-scoped throttling: the rate-limiting reference defines it as "the User whose token is being used in the request has reached their rate limit." Platform rate limits are computed per app-user pair on a rolling window, so this fires when the calls made with one user's token - across your app - exceed that user's allowance, even if the app as a whole is nowhere near its budget.

In Instagram messaging integrations, code 17 typically shows up in the connection and management paths rather than the send path: onboarding flows that enumerate Pages and Instagram accounts with a user token, dashboards that refresh account metadata for many workspaces authorized by the same person, or agency setups where one staff account authorized dozens of client integrations and every one of them polls with tokens derived from that single user. Sends made with a Page token are more likely to hit 32 or 4.

The fix is the standard throttling discipline plus one structural change: stop concentrating so much traffic behind one human's identity.

Why it happens

  • Onboarding or dashboard code polls /me/accounts and account metadata with the same user token at high frequency.
  • One agency user authorized many client accounts, concentrating all their API traffic on a single app-user pair.
  • A background sync iterates every connected workspace using tokens derived from the same user session.
  • Retry loops on a failing user-token call, each attempt counting against the same user budget.

How to fix Instagram error 17

  1. 1Back off: pause calls made with that user's token until the rolling window drains, watching X-App-Usage percentages on responses.
  2. 2Cache the results of account-enumeration calls; Page and Instagram account IDs almost never change between sessions.
  3. 3Use Page access tokens for all runtime messaging work so steady-state traffic is not user-scoped.
  4. 4Spread client integrations across the users who actually own them instead of one shared staff login.
  5. 5Rate-limit management-plane jobs independently of the messaging path so a dashboard refresh cannot throttle authentication flows.

How to stop it recurring

Keep the user token for what only it can do - the login exchange and the initial account listing - and persist everything it returns. Runtime traffic should ride on Page tokens or Instagram-Login account tokens, leaving the per-user budget essentially idle. The platform formula (calls per hour scaled by users) and the messaging-specific per-second ceilings are tabulated in the Instagram limits reference.

Official reference: Meta for Developers - Messenger Platform error codes. See all Instagram error codes or the Instagram limits and quotas.

Related codes

Error 17 - quick answers

What does Instagram error 17 mean?

Code 17 is user-scoped throttling: the rate-limiting reference defines it as "the User whose token is being used in the request has reached their rate limit." Platform rate limits are computed per app-user pair on a rolling window, so this fires when the calls made with one user's token - across your app - exceed that user's allowance, even if the app as a whole is nowhere near its budget.

How do I fix Instagram error 17?

1. Back off: pause calls made with that user's token until the rolling window drains, watching X-App-Usage percentages on responses. 2. Cache the results of account-enumeration calls; Page and Instagram account IDs almost never change between sessions. 3. Use Page access tokens for all runtime messaging work so steady-state traffic is not user-scoped. 4. Spread client integrations across the users who actually own them instead of one shared staff login. 5. Rate-limit…

Can I retry after error 17?

Yes - this is a retryable condition. Back off (start around one second and double on each attempt, with jitter) and watch for a retry-after hint from the platform before resending.

Stop debugging Instagram by hand

Connect the channel through Conferbot: tokens, webhooks and retries are handled, failures show as readable status.