Error Handling, iOS SDK

To build a robust and reliable app you want to make sure that it properly responds to errors returned by Facebook. This guide covers features in the Facebook SDK for iOS which help you do this.

General Best Practices

Each FBSDK Kit defines a FBSDK*Constants.h file which defines error codes relevant to that Kit.

More importantly, the Facebook SDK populates keys defined in FBSDKConstants.h in FBSDKCoreKit.framework in the userInfo dictionary of NSErrors where possible.

You should display only the localized messages as errors. One exception is Graph API requests that utilize the automatic error recovery described below.

Error Handling and Recovery

As of v4.0 of the SDK, error objects and information are now easier to extract and interpret. This includes:

  • NSError - The SDK returns these objects for request callbacks and they are easier to interpret
  • NSErrorRecoveryAttempting - The SDK provides data in NSError which is easier to extract and conforms to the informal protocol NSErrorRecoveryAttempting

NSError objects have userInfo dictionaries that contain the following keys:

Error Description

FBSDKErrorDeveloperMessageKey

An error message for the developer

FBSDKErrorLocalizedDescriptionKey

A localized user facing message, if available

FBSDKErrorLocalizedTitleKey

A localized user facing title, if available

FBSDKGraphRequestErrorCategoryKey

An enum describing if the error category, such as transient, recoverable, other

FBSDKGraphRequestErrorGraphErrorCode

The Graph API error code

FBSDKGraphRequestErrorErrorSubcode

The Graph API error subcode

FBSDKGraphRequestErrorHTTPStatusCodeKey

The HTTP status code returned by the Graph API

FBSDKGraphRequestErrorParsedJSONResponseKey

The raw JSON response from the Graph API


NSError instances may also contain data conforming to the informal protocol NSErrorRecoveryAttempting. If the category (FBSDKGraphRequestErrorCategoryKey) is transient or recoverable, the error userInfo contains:

Error Description

NSRecoveryAttempterErrorKey

A recovery attempter conforming to <FBSDKErrorRecoveryAttempting> that conforms to informal protocol <NSErrorRecoveryAttempting>

NSLocalizedRecoverySuggestionErrorKey

A localized user facing message describing the recovery

NSLocalizedRecoveryOptionsErrorKey

An array of localized labels for buttons describing the recovery options

Login Error Handling

Errors rarely occur in the typical login flow because the login dialog presented by Facebook via single sign on guides the users to resolve any errors. There are two exceptions you need to consider:

  • If you specified a login behavior of FBSDKLoginBehaviorSystemAccount
  • Handling declined permissions

FBSDKLoginBehaviorSystemAccount

In the case of FBSDKLoginBehaviorSystemAccount, the UI is provided by iOS natively. As a result, there can be errors that require user action to resolve such as if they changed their password on www.facebook.com or their account has been disabled for security reasons.

In those cases the login API will provide an appropriately coded NSError instance (with the above localized keys) that you can display. Note FBSDKLoginBehaviorSystemAccount is not the default login behavior, and the other login behaviors will provide appropriate messaging in the login dialog automatically.

Handling Declined Permissions

This is technically not an error condition as no NSError instance is returned, but an important scenario to consider nonetheless. FBSDKAccessToken provides a declinedPermissions property which describes all the permissions the user has declined for your application over their lifetime. This includes any declines on other devices.

More convenient is the declinedPermissions property on FBDKLoginResult which is returned to the FBSDKLoginManager callback or FBSDKLoginButton delegate. The FBSDKLoginResult.declinedPermissions reflects the declined permissions in the associated request and is a good place to check if the user has declined some of the permissions you requested.

If the user declines permissions, you should not immediately ask for them again. Instead your app should continue functioning. You may consider providing a guide or user interface explaining the benefits of granting that permission but should only ask for it again if the user performs an action that needs it.

Handling Graph API Errors

You may encounter different kinds of errors when working with the Graph API such as:

  • Request throttling on Facebook's servers
  • Missing parameters
  • Insufficient permissions

More importantly, users might have taken actions outside of your app that would change the access token's authorization and result in a Graph API error

  • Removing your app from App Settings on Facebook
  • De-authorizing permissions for your app
  • Changing their Facebook password

To help with these scenarios, the Facebook SDK populates additional keys in the NSError userInfo:

Error Description

FBSDKGraphRequestErrorCategoryKey

An enum describing if the error category. Includes transient, recoverable, other.

FBSDKGraphRequestErrorErrorCode

The Graph API error code.

FBSDKGraphRequestErrorErrorSubcode

The Graph API error subcode.

FBSDKGraphRequestErrorHTTPStatusCodeKey

The HTTP status code returned by the Graph API.

FBSDKGraphRequestErrorParsedJSONResponseKey

The raw JSON response from the Graph API.


So for example, to check if the error was permissions related, you can inspect the code value to see if it is equal to 200. See Using Graph API, Handling Errors.

Error Recovery

NSError instances may also contain data conforming to the informal protocol NSErrorRecoveryAttempting. Specifically, if the category (FBSDKGraphRequestErrorCategoryKey) is transient or recoverable, the error userInfo contains:

Error Description

NSRecoveryAttempterErrorKey

A recovery attempter conforming to <FBSDKErrorRecoveryAttempting> which conforms to informal protocol <NSErrorRecoveryAttempting>

NSLocalizedRecoverySuggestionErrorKey

A localized user facing message describing the recovery.

NSLocalizedRecoveryOptionsErrorKey

An array of localized labels for buttons describing the recovery options.


This allows you to easily extract the recovery attempter and ask it to attempt to recover from the error, which may prompt UI for the user. For example, if the token is expired the recovery attempter will ask the user if they want to log in again. The attempter will notify its delegate upon recovery success or failure. See Apple's documentation on Error Recovery.

To make it simpler to subscribe to best practices, the SDK provides FBSDKGraphErrorRecoveryProcessor which can process errors for you, such as presenting alerts or dialogs automatically. See its reference docs for details.

More importantly, non-batched FBSDKGraphRequests will automatically use FBSDKGraphErrorRecoveryProcessor so that transient errors and recoverable errors that succeed are automatically retried (once). You can disable this by setting -[FBSDKGraphRequest setGraphErrorRecoveryDisabled:YES] (or disable globally in FBSDKSettings)

Sharing Errors

The ShareKit APIs follow the above information with regards to the data in NSError userInfo dictionaries and may wrap the errors so you should consider inspecting the NSUnderlyingError key. Additionally, the FBSDKShareAPI uses FBSDKGraphRequests internally which follows the error recovery behavior outlined above. If that is not desired, you should disable the error recovery globally via [FBSDKSettings setGraphErrorRecoveryDisabled:YES].