Retries and idempotency
Retry safely with an Idempotency-Key. A replayed answer is never charged twice.
Send an Idempotency-Key header with any string up to 255 characters. Use a new key for each logical request and the same key for its retries.
curl -s "https://scraper.riken.me/v1/tiktok/profile?handle=example_creator" \
-H "x-api-key: $RIKEN_API_KEY" \
-H "Idempotency-Key: profile-example_creator-2026-11-11"How it behaves
| case | result |
|---|---|
| same key, same parameters, within 24 hours | the stored answer comes back with Idempotent-Replay: true. Not charged again. |
| same key, other parameters | a new request, charged on its own. The key is bound to the parameters. |
| same key while the first request still runs | 409 idempotency_conflict with Retry-After: 1. Wait and retry. |
| the first answer was an error or free | nothing was stored, so the retry runs again |
| another API key, same Idempotency-Key | unrelated. Replays never cross API keys. |
Only charged answers are stored.
A retry loop
import time, uuid, requests
def get(url, key, params):
idem = str(uuid.uuid4())
for attempt in range(5):
r = requests.get(url, params=params, timeout=200,
headers={"x-api-key": key, "Idempotency-Key": idem})
if r.status_code in (409, 429, 503) or r.status_code >= 500:
time.sleep(int(r.headers.get("Retry-After", 2 ** attempt)))
continue
return r
return r