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 3 minutes of execution time within a 1 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: 5 X-PROCESSING-TIME: 200 X-THROTTLE-WINDOW-SIZE: 60000 X-THROTTLE-MILLIS-USED: 200 X-THROTTLE-MILLIS-LEFT: 41859 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.
||The amount of execution time that is allowed within the window.|
||The amount of execution time, in milliseconds, that has been used in the window.|
||The amount of execution time, in milliseconds, that is remaining in the window.|
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.
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.