Access Tokens: Debugging and Error Handling

Getting Info about Tokens and Debugging

When working with an access token, you may need to check what information is associated with it, such as its user or expiry. To get this information you can use our debug tool, or you can use the API endpoint.

To use the API, you can issue a Graph API request:

curl -i -X GET "https://graph.facebook.com/debug_token?
  input_token={input-token}&
  access_token={valid-access-token}

Replace {input-token} with the access token you want to get information about and {access-token} with a valid access token. The tokens must be from the same app.

The response of the API call is a JSON array that looks like this:

{
  "data":{
    "app_id":"{app-id}",
    "type":"USER", 
    "application":"{app-name}",
    "data_access_expires_at":1576687825, 
    "expires_at":1570820400,             
    "is_valid":true,
    "scopes":[
      "pages_show_list",
      "public_profile"
    ],
    "granular_scopes":[
      {
        "scope":"pages_show_list",
        "target_ids":[
          "{page-1-app-can-access-id}",
          "{page-2-app-can-access-id}"
        ]
      }
    ],
    "user_id":"10215241773831025"
  }
}

For long-lived access tokens the issued_at field is also returned.

Handling Errors

Facebook will not notify you that an access token has become invalid. Unless you have sent the expiry time to your app along with the access token, your app may only learn that a given token has become invalid when you attempt to make a request to the API.

In most apps, the best way to handle expired tokens is to capture the error messages thrown by the API. In each case, the API will return an error message, a code, and a subcode in a JSON body explaining the nature of the error. For more information on codes and subcodes please see the error code reference doc.

Expired or invalid access tokens

Expired Token Sample Response

{
  "error": {
    "message": "Error validating access token: Session has expired on Wednesday, 14-Feb-18 18:00:00 PST. The current time is Thursday, 15-Feb-18 13:46:35 PST.",
    "type": "OAuthException",
    "code": 190,
    "error_subcode": 463,
    "fbtrace_id": "H2il2t5bn4e"
  }
}

Invalidated Token Sample Response

This response is sent when a person logged out of your app or changed their password.

{
  "error": {
    "message": "Error validating access token: The session is invalid 
                because the user logged out.", 
    "type": "OAuthException", 
    "code": 190,
    "error_subcode": 460,
    "fbtrace_id": "H2il2t5bn4e"
  }
}

The person will need to login again to get a valid access token so you can make API calls on their behalf. The login flow your app uses for new people should determine which method you need to adopt.

App Authorization Error Sample Response

When someone has revokes authorization or has never authorized your app, the error response will be the same as for a person who is new to your app.

De-authorized Token Sample Response

{
  "error": {
    "message": "Error validating access token: User {user-id} has 
                not authorized application {your-app-id}.", 
    "type": "OAuthException", 
    "code": 190,
    "error_subcode": 458,
    "fbtrace_id": "H2il2t5bn4e"
  }
}
}

Handling Token Errors in iOS Apps

API errors in the iOS SDK are typically surfaced through the NSError instances passed to the callbacks. See the iOS SDK error documentation for more details.

Handling Token Errors in Android Apps

API errors in the Android SDK are typically surfaced via the Response object passed to the Requests's callback. Specifically, you can call response.getError() to retrieve a FacebookRequestError instance.

Learn More

You can read about more errors in our API Error reference but these three errors are the most common when dealing with access tokens.