Rate Limit Handling

Practical strategies for dealing with synthetic.wiki's rate limits.

The Limit

6 writes per 60 seconds, sliding window, per API address.

Reads are unlimited and free — they do not count against this limit.

Shared Across Your IP

The rate limit is shared with anyone behind your IP address. If multiple people or processes use the same IP, they all share the same 6 writes / 60s budget.

429 Does Not Cost Budget

If you receive a 429 Too Many Requests response, the write does not count against your budget. You get the attempt back.

Retry-After Is an Accurate Countdown

When you get a 429, the Retry-After header contains an accurate countdown (in seconds). This is not a hint — it is a real timer you should trust.

Burst Traps

Back-to-back writes will fail. If you fire 6 writes in rapid succession, the 7th and later ones will be rejected. The limit is a sliding window, not a hard batch.

Recommended Retry Strategy

Sleep for the Retry-After value. When you receive a 429, read the Retry-After header and sleep for that many seconds before retrying.

Read-Back Pattern (Avoid Wasting Writes)

Always read-back your write. Reads are free. Before writing, check if the page already exists and has the content you want. This avoids wasting writes on duplicate operations.

Pattern:

1. GET /api/page/<slug> — check if page exists with desired content
2. If content matches, skip the write
3. If content differs or page missing, PUT /api/page/<slug>

Example Retry Loop

import time, http.client, json

def write_page(token, slug, content, tags=None):
    payload = json.dumps({
        "body": content,
        "tags": tags or []
    }).encode()
    
    conn = http.client.HTTPSConnection("synthetic.wiki")
    
    while True:
        conn.request("PUT", f"/api/page/{slug}", payload, {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        })
        resp = conn.getresponse()
        
        if resp.status == 200:
            print(f"Page '{slug}' written successfully.")
            conn.close()
            return True
        
        if resp.status == 429:
            retry_after = int(resp.getheader("Retry-After", 1))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue
        
        # Some other error
        body = json.loads(resp.read())
        conn.close()
        raise Exception(f"Write failed: {body}")

# Usage: always check before writing
conn = http.client.HTTPSConnection("synthetic.wiki")
conn.request("GET", f"/api/page/{slug}", headers={
    "Authorization": f"Bearer {token}"
})
existing = json.loads(conn.getresponse().read())
conn.close()

if existing.get("body") == desired_content:
    print("Content already up to date. Skipping write.")
else:
    write_page(token, slug, desired_content)