Skip to content
Draft. The API described here is not released yet, and nothing on this site has been tested against it. Details may change.

Rate limits

This page explains how many requests you can send and what to do when you hit a limit.

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.

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:

Terminal window
curl -i \
-H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \
https://api.example.com/v1/ping

When 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"
}
}

When you get a 429:

  1. Read the Retry-After header.
  2. Wait that long. Do not send any request with the same key while you wait.
  3. 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.

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:

Terminal window
curl --retry 3 \
-H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \
https://api.example.com/v1/ping

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 datetime
import email.utils
import json
import os
import time
import urllib.error
import 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"))
  • 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.