Throttling

Requests to the FamilySearch API may be rate-limited on a per-user basis. This means that even if a user has two different active sessions with two different products, their requests are all still throttled together.

Throttling policies are established in terms of the amount of processing time per real time. For example, requests could be given 30 minutes of execution time within a 10 minute window.

Throttling is implemented on a per-user basis. If a user is not signed-in, the app key is used. An app that does not use threads may still receive a throttled response if a user has a session open with another product that uses the FamilySearch API.

When the throttling limit is reached, the server responds with an HTTP status code of 429 and a Retry-After header that advises how many milliseconds to wait to make another request.

Server: Apache-Coyote/1.1
Retry-After: 500
X-PROCESSING-TIME: 43
Content-Type: application/x-fs-v1+xml
Transfer-Encoding: chunked
Date: Thur, 01 May 2014 18:55:13 GMT
Connection: close

All responses from FamilySearch servers include the X-PROCESSING-TIME header to help you track the execution time elapsed in milliseconds. This header can be used by developers to apply a correct rate-limiting policy to their application. Information regarding window size, processing time used and processing time remaining will also be returned in a header.

Response Headers Description
X-THROTTLE-WINDOW-SIZE The amount of execution time that is allowed within the window.
X-THROTTLE-MILLIS-USED The amount of execution time, in milliseconds, that has been used in the window.
X-THROTTLE-MILLIS-LEFT The amount of execution time, in milliseconds, that is remaining in the window.