Error Handling, iOS SDK

%FB(devsite:markdown-wiki:related-links-card { title: 'Related Topics', links: [ 'Graph API, Handling Errors', 'FBSDK Error Recovery', 'Test a Login Flow', 'Apple, Error Objects',

], })

To build a robust and reliable app you want to make sure that it properly responds to errors returned by the 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)