Rate Limits

Tier Limits

Free tier workspaces cannot use API keys. API key access requires Starter or above.

Exceeding Limits

When you exceed your rate limit, the API returns 429 Too Many Requests. Use the Retry-After header to determine when to retry.

# Check the Retry-After header for how long to wait
curl -v -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/mapping

# Response when rate limited:
# HTTP/1.1 429 Too Many Requests
# Retry-After: 5

Best Practices

• Implement exponential backoff with jitter for retries
• Cache responses when possible to reduce request volume
• Use polling intervals of 5-10 seconds for status checks (avoid tight loops)
• Contact support if you need higher limits for Enterprise tier

Automatic retry in the SDKs

The Nopaque SDKs auto-retry on 429 responses - they honor the server's Retry-After header, so you do not need to add backoff manually. Defaults: 3 retries with exponential jitter, capped at 8 seconds. You can tune or disable this behavior.

from nopaque import Nopaque

# Disable retries entirely
client = Nopaque(max_retries=0)

# Custom retry count + observability hook
def log_retry(attempt, err, next_delay):
    print(f"attempt {attempt}: {type(err).__name__} → retrying in {next_delay:.1f}s")

client = Nopaque(max_retries=5, on_retry=log_retry)

# Per-call override
job = client.mapping.get("map_abc123", request_options={"max_retries": 0})

Important: POST requests that create or mutate state are only retried on 429 and pre-flight connection errors, never on 5xx or in-flight timeouts. This avoids duplicate side effects since the API does not support idempotency keys. If you need to retry a POST after a 5xx, call the method again yourself.