Messenger Platform · error code

Messenger error 10303: Invalid account_linking_token

RetryableAccess tokens & authentication

Last verified against Meta for Developers - Messenger Platform error codes

What Messenger returns
Account Linking Error: Invalid account_linking_token.

What error 10303 means

Code 10303 belongs to Messenger account linking, the flow that connects a person's Messenger identity to a login in your own system: "Account Linking Error: Invalid account_linking_token." When someone taps a Log In button, Messenger opens your account linking URL with two query parameters appended, account_linking_token and redirect_uri. You can exchange that token for the person's PSID through the PSID retrieval endpoint, and you must pass the token flow back through the redirect to finish linking.

The account linking guide describes the token as short-lived: it "is only valid for 5 minutes, it is encrypted and unique per user." Most 10303 errors come from that window. A login page with password reset, two-factor prompts or a slow SSO hop can easily take longer than five minutes, and the token expires before your backend calls the endpoint.

The error is about the token only. Your Page access token, webhook subscription and the rest of the bot are fine, and a fresh attempt from a new Log In tap will produce a new token.

What it looks like

{
  "error": {
    "message": "(#10303) Account Linking Error: Invalid account_linking_token.",
    "type": "OAuthException",
    "code": 10303,
    "fbtrace_id": "BLBz/WZt8dN"
  }
}

Why it happens

  • The login flow took longer than the token's 5-minute validity.
  • The token was altered in transit: double URL-decoding, truncation, or stripped characters.
  • Calling the PSID retrieval endpoint with a Page access token from a different Page.
  • Reusing a token captured from an earlier linking attempt.
  • Starting the flow from somewhere other than a Log In button, so no valid token was issued.

How to fix Messenger error 10303

  1. 1Call GET /me?fields=recipient&account_linking_token=TOKEN with the same Page's token as soon as your callback receives it.
  2. 2Pass the token through your login flow exactly as received; decode once at most.
  3. 3If the token has expired, send the person a new Log In button and restart the flow.
  4. 4On failure, redirect to redirect_uri without authorization_code so Messenger closes the flow cleanly.
  5. 5Confirm the app is subscribed to the messaging_account_linking webhook, which the guide says is required for linking to complete.

How to stop it recurring

Keep the linking page short: resolve the PSID immediately on callback, before any slow login steps, and store it in your session. Remember that account linking runs only in the iOS and Android Messenger apps and only from Log In buttons. Webhook subscription problems that silently break linking are covered in the webhook debugging guide.

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

Related codes

Error 10303 - quick answers

What does Messenger error 10303 mean?

Code 10303 belongs to Messenger account linking, the flow that connects a person's Messenger identity to a login in your own system: "Account Linking Error: Invalid account_linking_token." When someone taps a Log In button, Messenger opens your account linking URL with two query parameters appended, account_linking_token and redirect_uri .

How do I fix Messenger error 10303?

1. Call GET /me?fields=recipient&account_linking_token=TOKEN with the same Page's token as soon as your callback receives it. 2. Pass the token through your login flow exactly as received; decode once at most. 3. If the token has expired, send the person a new Log In button and restart the flow. 4. On failure, redirect to redirect_uri without authorization_code so Messenger closes the flow cleanly. 5. Confirm the app is subscribed to the messaging_account_linking webhook,…

Can I retry after error 10303?

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 Messenger by hand

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