Error Codes and Troubleshooting for Delegated Account Recovery

Debug your recovery issues.

This document gives troubleshooting tips and lists the set of error codes you may encounter when developing with Facebook's Delegated Account Recovery system.

Troubleshooting Hints

Use a low max-age for your configuration until it is stable

Configuration fetches are done server-to-server, and Facebook uses hints such as the max-age value in the HTTP Cache-Control header to determine how often to check for updates. Errors are also cached for a minimum period of time. Deliberately set a low max-age until your configuration stabilizes, then turn it up to a larger value (like a week) to minimize delays for users.

Rate limiting: avoid testing with real accounts

As a security precaution, ordinary accounts are strictly rate limited as to how quickly they may recover external accounts from Facebook. You should use a Whitehat test account for testing as they are exempt from these rate limits.

Publish keys with overlapping time windows

Publish two keys, but use only one at a time. Continue to use the current key for some period of time after you publish a new one, and keep the previous key published for some period of time after you stop using it, so that Facebook will always have the valid key for your service at any time, even if we have cached your configuration.

Don't block access to your configuration

The well-known configuration is retrieved in a server-to-server call as part of the delegated account recovery protocol. If your web site blocks programmatic clients like curl based on user-agent strings, you may prevent Facebook from being able to retrieve your configuration.

Error Codes

You or your users may occasionally encounter error codes while using the system. Proper operation of Delegated Account Recovery depends on your system interfacing correctly with Facebook. You can look up the error codes you see to help troubleshoot and fix problems.

Error Code Message Note

001

Please check the referring site and try again later.

A recovery token was sent to Facebook and the audience value was not set to https://www.facebook.com. The token audience is a security feature and must match the issuer value of Facebook's published configuration.

002

Please check the referring site and try again later.

A recovery token was sent to Facebook with an invalid value for the issuer field. This field must contain an ASCII-serialized origin, with the scheme set to https: and no trailing slash, as per RFC6454.

003

Please check the referring site and try again later.

Facebook could not retrieve or parse your service's configuration. Verify that it is being served at the correct, well-known location, that it is valid JSON containing all required values, and that user-agent string at your service do not refuse service to non-browser clients like curl.

004

Please check the referring site and try again later.

The token your service sent to Facebook exceeded the published max-size value.

005

A system issue occurred. Please try again.

Facebook system issue.

006

Please check the referring site and try again later.

The initiation of delegated account recovery flows must be done with a POST request. GET is not allowed.

007

This request may have timed out. Please go back to the other site and try again.

The request to Facebook may not have contained a token in the POST data with the correct parameter name, or the request may have timed out because the user did not act quickly enough on the consent prompt.

008

Please check the referring site and try again later.

The signature on the token Facebook received was invalid. Verify your signing code and that you are publishing the correct public keys in your configuration.

009

Please check the referring site and try again later.

The recovery token contained a token binding that could not be validated against the currently logged in user's session, browser, IP address and time. If you set a token binding , it must be used in a timely fashion and only from the same browser context in which it was issued. You must only retrieve the token binding value directly from Facebook using the asynchronous postMesasge API. If you do not wish to use a token binding, set the length field of that portion of the token to 0.

010

We're sorry, we cannot complete this action due to a mistake or misconfiguration at the site or application that directed you here. Please inform them of the error. (Duplicate Token ID. Perhaps you have already saved this token?)

The ID of every token from a given issuer must be unique. Token IDs are 128 bits, and it is recommended that they contain at least 96 bits of entropy.

011

Please check the referring site and try again later.

Facebook could not parse the token sent to us.

012

This request may have timed out. Please go back to the other site and try again.

The user may have waited too long to complete the action or your service's clock may be too far out of sync with network time.

013

Please check the referring site and try again later.

The referenced token did not exist.

014

A system issue occurred. Please try again.

Facebook system error.