Rate limits

How limits are applied

Limits are fixed technical ceilings applied per calling address over a rolling window - they are the same on every plan. (Your plan instead controls usage allowances, like included call minutes or AI tokens - see your dashboard usage panel for those.)

What happens at the limit

You receive HTTP 429 with the message "Too many requests. Please try again shortly." Nothing is created, and the request can be safely retried later. Standard RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset response headers are included on every request so you can back off before you actually hit the ceiling rather than discovering it via a 429.

# Exponential backoff with jitter
attempt=0
until [ $attempt -ge 5 ]; do
  code=$(curl -s -o /tmp/r.json -w '%{http_code}' \
    -H "X-SIMCOAI-API-Key: $SIMCOAI_API_KEY" "https://api.simcoai.co.uk/v1/orders")
  [ "$code" != "429" ] && break
  attempt=$((attempt+1))
  sleep $(( (2 ** attempt) + (RANDOM % 3) ))
done

Staying well under

• Batch instead of polling per record. One list call beats fifty single fetches.
• Use webhooks rather than polling. Let SIMCOAI tell you when something changes.
• Cache /v1/me. Scopes rarely change; there is no need to call it per request.
• Put a ceiling on retries. An unbounded retry loop is the usual cause of a sustained 429.
• Read the RateLimit-Remaining header. It tells you how much headroom is left in the current window before you need to slow down.

See also API errors for the full list of error codes, and idempotency for safely retrying a request that may have already succeeded.