Rate Limits - Wordsmith API

The Wordsmith API applies rate limits per organisation so that one integration’s traffic burst cannot slow the platform down for anyone else. The limits are deliberately generous: a well-behaved integration should never see one.

Current Limits

Limit	Scope	Value
New sessions	Per organisation	60 per minute
API requests	Per organisation	400 per minute

A few things worth knowing about how these behave:

They are shared across your whole organisation, not per API key or per user. Creating additional keys does not raise your limit.
They refill continuously, rather than resetting on a fixed schedule. The “new sessions” limit means you can submit 60 new questions at once, after which capacity returns at roughly one per second. There is no cliff edge at the top of the minute.
Only new sessions count towards the session limit. Follow-up questions sent to an existing session — by passing session_id to Create Question — count only towards the overall request limit. Grouping related questions into one session is both faster and cheaper on your limit.
Polling counts as a request, and it is what most integrations spend their request limit on. Each call to Get Question Status uses one, and polling has to share the limit with the calls that create the questions in the first place. At one poll per question every ten seconds, around 30 questions in flight leaves you comfortable headroom; polling every second, six or seven questions is all your budget stretches to. If you need to track more than that at once, pass a callback_url and let a webhook tell you when each answer is ready — that removes polling from your budget entirely, and it is the approach we recommend for any integration running at volume.

When You Are Rate Limited

The API responds with HTTP 429 and a Retry-After header telling you exactly how many seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json

{
  "error_code": "rate_limit_exceeded",
  "message": "Rate limit exceeded: at most 60 new sessions created by your organisation per minute. Retry in 1 second, then back off exponentially if you are limited again.",
  "retry_after_seconds": 1,
  "limit": 60,
  "limit_window_seconds": 60
}

integer

Seconds to wait before retrying. Always matches the Retry-After header.

integer

The maximum number of operations allowed in the window.

integer

The length of the window the limit applies over, in seconds.

A 429 means the request was rejected before any work started, so it is always safe to retry.

Handling Limits Gracefully

Honour Retry-After, then back off exponentially if you are limited repeatedly. This keeps your integration moving at the fastest rate we can serve without you having to guess at a delay.

import time
import requests

def create_question(payload, max_attempts=6):
    delay = None
    for attempt in range(max_attempts):
        response = requests.post(
            "https://api.wordsmith.ai/api/v1/assistants/default/questions",
            headers={"Authorization": "Bearer sk-ws-api1-your_key"},
            json=payload,
        )

        if response.status_code != 429:
            response.raise_for_status()
            return response.json()

        # Wait at least as long as we are asked to, backing off further if we are limited again.
        retry_after = int(response.headers.get("Retry-After", 1))
        delay = retry_after if delay is None else min(max(retry_after, delay * 2), 60)
        time.sleep(delay)

    raise RuntimeError("Still rate limited after retrying")

If you are queuing a large batch of work, pacing your submissions to stay under the limit is better than submitting everything and retrying the rejections — you will finish sooner and with fewer wasted calls.

Need a Higher Limit?

If your use case genuinely needs more headroom, email support@wordsmith.ai with a description of your workload and the throughput you need. We would much rather raise your limit than have you throttled.

​Current Limits

​When You Are Rate Limited

​Handling Limits Gracefully

​Need a Higher Limit?

Current Limits

When You Are Rate Limited

Handling Limits Gracefully

Need a Higher Limit?