Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spotzee.com/llms.txt

Use this file to discover all available pages before exploring further.

Every API key has a per-second budget for read and write operations. Limits are tuned to be generous for parallel agent workloads and bursty fan-out from MCP servers.

​
Limits per plan

Limits are per second per API key, with a 10-second sliding window that absorbs short bursts.
PlanRead req/sWrite req/sBurst (10s window)
Starter2001001.5×
Professional1,0005001.5×
Enterprise5,0002,5002×
Read covers GET, HEAD, OPTIONS. Write covers POST, PATCH, PUT, DELETE.

​
MCP and agent workloads

If you’re driving the API from an MCP server or agent runtime, send the x-spotzee-client-type: mcp header. Spotzee doubles your base limits when this header is present so parallel tool calls don’t run out of budget mid-task. 
x-spotzee-client-type: mcp

​
Response headers

Every successful response includes the current state of your bucket so you can self-throttle without trial and error.
HeaderMeaning
X-RateLimit-LimitMaximum requests over the 10-second window for this key + bucket (read or write)
X-RateLimit-RemainingRequests still available in the current window
X-RateLimit-ResetSeconds until the window expires
X-RateLimit-TierThe plan tier applied to your key (starter, professional, enterprise)

​
When you hit the limit

You receive 429 Too Many Requests with a Retry-After header (seconds) and a standard error body: 
HTTP/1.1 429 Too Many Requests
Retry-After: 6
Content-Type: application/problem+json

{
  "status": "error",
  "code": "rate_limited",
  "title": "Rate limit exceeded",
  "message": "Rate limit exceeded. Slow down and retry after the period in `Retry-After`.",
  "type": "https://docs.spotzee.com/main-api/errors#rate_limited",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2"
}

​
Retry strategy

1

Honour Retry-After first

Wait at least the number of seconds in Retry-After before retrying. This is the lowest-risk path and almost always succeeds on the next attempt.
2

Add jitter

If you’re driving many keys in parallel, add 0–500 ms of jitter on top of Retry-After so retries don’t synchronise.
3

Back off on repeats

If you see a second 429 after honouring Retry-After, double your delay (exponential backoff) up to a sensible cap — for example, 60 seconds.
4

Cap concurrency

X-RateLimit-Remaining is the most reliable signal. Pause new requests once it falls below your fan-out width.

​
Self-throttling example

async function callApi(path, init) {
  const res = await fetch(`https://apix.spotzee.com/api/client${path}`, init)

  if (res.status === 429) {
    const retryAfter = Number(res.headers.get('Retry-After') ?? '5')
    await new Promise(r => setTimeout(r, retryAfter * 1000))
    return callApi(path, init)
  }

  // Self-throttle when nearly empty
  const remaining = Number(res.headers.get('X-RateLimit-Remaining') ?? '0')
  if (remaining < 50) {
    await new Promise(r => setTimeout(r, 250))
  }
  return res
}

​
Quota-metered endpoints

A small set of endpoints (validation, scoring, and other quota-billed operations) consumes credits in addition to the per-second budget. Hitting your credit balance returns 402 quota_exceeded even when your rate-limit headers show capacity remaining.

​
Next steps

Idempotency

Make retries safe.

Errors

Status codes and the code catalogue.