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:

GET /debug_token?
  input_token={input-token}&
  access_token={access-token}
  • input_token: the access token you want to get information about
  • access_token: your app access token or a valid user access token from a developer of the app

The response of the API call is a JSON array containing a map of fields. For example:

{
    "data": {
        "app_id": 000000000000000, 
        "application": "Social Cafe", 
        "expires_at": 1352419328, 
        "is_valid": true, 
        "issued_at": 1347235328, 
        "scopes": [
            "email", 
            "publish_actions"
        ], 
        "user_id": 1207059
    }
}

Note that the issued_at field is not returned for short-lived access tokens.

Handling Errors

Facebook doesn't notify you that a previously issued access token has become invalid. Unless you have persisted the expiry time passed to your App along with the access token, your app may only learn that a given token has become invalid is when you attempt to make a request to the API. Also, in response to certain events that are security-related, access tokens may be invalidated before the expected expiration time.

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 HTTP 400 status code, a code and a subcode in a JSON body explaining the nature of the error. (These examples don't include a subcode, but subcodes are described in the error reference.)

Expired or invalid access tokens

Access Token has expired

{
  "error": {
    "message": "Error validating access token: Session has expired at unix 
                time SOME_TIME. The current unix time is SOME_TIME.", 
    "type": "OAuthException", 
    "code": 190
  }
}

Access Token invalidated due to the person logging out or changing their password

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

If the access token becomes invalid, the solution is to have the person log in again, at which point you will be able to make API calls on their behalf once more. The login flow your app uses for new people should determine which method you need to adopt.

Person has de-authorized your app

{
  "error": {
    "message": "Error validating access token: User USER_ID has 
                not authorized application APP_ID.", 
    "type": "OAuthException", 
    "code": 190
  }
}
}

When someone has de-authorized your app it should treat someone as if they are new to the app.

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

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.

Access Token Length

Expect that the length of all access token types will change over time as Facebook makes changes to what is stored in them and how they are encoded. You can expect that they will grow and shrink over time. Please use a variable length data type without a specific maximum size to store access tokens.