Rate limits
This page explains how many requests you can send and what to do when you hit a limit.
What are the limits?
Section titled “What are the limits?”| What is limited | The limit |
|---|---|
| Requests with one API key | 120 a minute |
| Requests from your whole firm, with all its API keys and connected apps together | 600 a minute |
Requests to /v1 from one IP address that the API refuses with 401 |
30 a minute. After that, requests from that address get 429. |
The size of a request body on /v1 |
64 KB |
The limit for one API key also applies to each connected app, such as Claude. Connected apps use an access token in place of an API key.
These numbers are set for the first release. SuperDocs may change them when the first customers use the API.
What happens when I hit a limit?
Section titled “What happens when I hit a limit?”The API answers with status 429 and a Retry-After header. Retry-After tells you how long to wait before you send another request.
You can see the status and the headers with the -i option of curl:
curl -i \ -H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \ https://api.example.com/v1/pingWhen you are over a limit, the status is 429, the headers include Retry-After, and the body is an error with the code rate_limited.
Example response:
{ "error": { "code": "rate_limited", "message": "...", "requestId": "example-request-id" }}How do I wait and try again?
Section titled “How do I wait and try again?”When you get a 429:
- Read the
Retry-Afterheader. - Wait that long. Do not send any request with the same key while you wait.
- Send the request again.
A 503 (service unavailable) also has a Retry-After header. Handle it the same way.
Do not try again at once, and do not try again in a tight loop. Always wait for the time in Retry-After.
Do not try again after a 401. Fix the key first. If too many requests from one address are refused with 401, that address gets 429 too.
With curl
Section titled “With curl”Recent versions of curl can wait and try again for you. With --retry, curl tries again after a 429 or a 503, and waits for the time in Retry-After:
curl --retry 3 \ -H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \ https://api.example.com/v1/pingWith Python
Section titled “With Python”This function sends a request. After a 429 or a 503, it waits for the time in Retry-After and tries again, up to 5 times. It uses only what comes with Python 3.
import datetimeimport email.utilsimport jsonimport osimport timeimport urllib.errorimport urllib.request
API_KEY = os.environ["SUPERDOCS_API_KEY"]
def seconds_to_wait(retry_after): # Retry-After is either a number of seconds or an HTTP date. if retry_after is None: return 60 # A safety net only. The API sends Retry-After with 429 and 503. if retry_after.strip().isdigit(): return int(retry_after) when = email.utils.parsedate_to_datetime(retry_after) now = datetime.datetime.now(datetime.timezone.utc) return max(0, (when - now).total_seconds())
def get(url, attempts=5): request = urllib.request.Request(url, headers={"Authorization": "Bearer " + API_KEY}) for attempt in range(attempts): try: with urllib.request.urlopen(request) as response: return json.load(response) except urllib.error.HTTPError as error: if error.code not in (429, 503) or attempt == attempts - 1: raise time.sleep(seconds_to_wait(error.headers.get("Retry-After")))
print(get("https://api.example.com/v1/ping"))How do I stay under the limits?
Section titled “How do I stay under the limits?”- Read big pages. Ask for up to 200 items on each page. See Paging.
- Send one request at a time with each key, unless you need more.
- Keep what you have read. Do not read the same data again and again.
- Remember the firm limit. Your firm’s API keys and connected apps share 600 requests a minute. One busy program can slow down the others.