Throttling

Requests to the FamilySearch API are rate-limited on a per-user basis. This means that even if a user has two different active sessions with two distinct 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 18 seconds of execution time within a 1 minute window. Different endpoints may have different throttling windows according to the load and sensitivity of the systems that service a particular endpoint.

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: 5
X-PROCESSING-TIME: 200
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. Developers can use this header to apply a correct rate-limiting policy to their application.

Service Unavailable

Traditionally an HTTP status code of 503 Service Unavailable response indicates that there was an internal issue preventing the service from responding. Where possible, a Retry-After header, indicates when that service will be available again.

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 60 seconds to the processing sum, specify this amount using the processingTime parameter (60 seconds/minute x 1000 milliseconds/second + 1 = 60001). Future requests from that user will be throttled until the throttling window expires.

Example Request

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

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