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. Different endpoints have different throttling windows.

Warning 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 Service Unavailable and a Retry-After header that advises how many seconds 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.

Testing Throttling

If you want to know how your application will respond to throttling events, you can test throttling. In order to do this, you can force the processing time counter to be larger than the throttling limit for the current user. Subsequent requests will determine that the current user has reached the throttling limit and the user will be throttled until the end of the current throttling window.

To do this, make a request to the Throttling Test resource, specifying the amount of time to be spent for the request. The processingTime parameter is the amount of time in milliseconds that you want to add to the sum of the processing time for the current user. For example, if you want to add 30 minutes to the processing sum, specify this amount using the processingTime parameter (30 minutes x 60 seconds/minute x 1000 milliseconds/second + 1 = 1800001). Future requests from that user will be throttled until the throttling window expires.

Example Request

  GET /platform/throttled?processingTime=1800001
  
  Authorization: Bearer YOUR_ACCESS_TOKEN_HERE

Some resources aren't throttled so be sure to use a throttled resource when testing.