NSP Rate Limiting: Limits, 429 Handling, and Config

NSP enforces per-API-key rate limits to prevent agent code from overwhelming the daemon and the monitored applications. The rate limiter uses a token bucket algorithm — short bursts above the limit are absorbed by the bucket’s capacity, but sustained request rates above the configured ceiling are throttled with a 429 Too Many Requests response.

Default Limits by Endpoint

Different endpoint categories carry different default limits, reflecting the relative cost of each operation.

Endpoint	Method	Default Limit	Config Key
`/apps`	`GET`	100 req/s	`rate_limit.state_per_second`
`/state`	`GET`	100 req/s	`rate_limit.state_per_second`
`/schema`	`GET`	100 req/s	`rate_limit.state_per_second`
`/diff`	`GET`	100 req/s	`rate_limit.state_per_second`
`/verify`	`GET`	100 req/s	`rate_limit.state_per_second`
`/action`	`POST`	10 req/s	`rate_limit.action_per_second`
`/learn`	`POST`	10 req/s	`rate_limit.action_per_second`
`/action` (`fresh=true`)	`POST`	2 req/min	`rate_limit.snapshot_per_minute`
`/health`	`GET`	No limit	—
WebSocket streams	—	No limit	—

Rate limits are tracked per API key. If you run multiple agents sharing one key, their requests all count toward the same bucket. Use a dedicated key per agent to isolate rate limits.

The 429 Response

When you exceed a rate limit, the daemon returns 429 Too Many Requests with a Retry-After header and a structured JSON body:

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

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 1 second.",
    "retry_after_ms": 1000
  }
}

Always read retry_after_ms (or the Retry-After header in seconds) and wait at least that long before retrying. Sending requests immediately after a 429 wastes your token budget and prolongs the throttle window.

Retry Strategy

Use exponential backoff when handling 429 responses. This prevents a flood of retries from cascading into further throttling.

Python SDK
curl / shell
Python (raw requests)

The Python SDK raises NSPRateLimitError on a 429 response. The retry_after attribute contains the wait time in seconds.

import asyncio
import nelieo_nsp as nsp

async def with_backoff(fn, max_retries: int = 5):
    """Call fn(), retrying with exponential backoff on rate limit errors."""
    for attempt in range(max_retries):
        try:
            return await fn()
        except nsp.NSPRateLimitError as e:
            if attempt == max_retries - 1:
                raise
            # Honour the daemon's hint, but apply exponential backoff on top.
            wait = max(e.retry_after, 2 ** attempt)
            print(f"Rate limited — retrying in {wait}s (attempt {attempt + 1}/{max_retries})")
            await asyncio.sleep(wait)

Parse the Retry-After header and sleep before the next attempt:

MAX_RETRIES=5
ATTEMPT=0

until [ $ATTEMPT -ge $MAX_RETRIES ]; do
  RESPONSE=$(curl -s -w "\n%{http_code}" \
    -H "X-Substrate-Key: $NSP_API_KEY" \
    http://localhost:7842/substrate/v1/apps)

  STATUS=$(echo "$RESPONSE" | tail -1)

  if [ "$STATUS" -ne 429 ]; then
    echo "$RESPONSE" | head -1
    break
  fi

  WAIT=$(( 2 ** ATTEMPT ))
  echo "429 received — sleeping ${WAIT}s before retry $((ATTEMPT + 1))"
  sleep $WAIT
  ATTEMPT=$((ATTEMPT + 1))
done

import time
import requests

def get_apps(api_key: str, max_retries: int = 5) -> dict:
    headers = {"X-Substrate-Key": api_key}
    for attempt in range(max_retries):
        resp = requests.get(
            "http://localhost:7842/substrate/v1/apps",
            headers=headers,
            timeout=10,
        )
        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 1))
            wait = max(retry_after, 2 ** attempt)
            print(f"Rate limited — retrying in {wait}s")
            time.sleep(wait)
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError("Exceeded max retries after repeated 429 responses")

How the Python SDK Surfaces Rate Limit Errors

NSPRateLimitError is raised any time the daemon responds with 429. The exception carries the following fields:

try:
    result = await session.execute("mark_read", parameters={"id": "msg_001"})
except nsp.NSPRateLimitError as e:
    print(e.message)       # "Rate limit exceeded. Retry after 1 second."
    print(e.code)          # "rate_limited"
    print(e.retry_after)   # 1.0  (seconds as a float)
    print(e.status_code)   # 429

Configuring Rate Limits in axon.toml

Adjust the defaults by editing the [rate_limit] section in axon.toml:

[rate_limit]
enabled = true

# Read endpoints: GET /state, /apps, /schema, /diff, /verify
state_per_second = 100

# Write endpoints: POST /action, POST /learn
action_per_second = 10

# Heap-snapshot requests (POST /action with fresh=true) — expensive, keep low
snapshot_per_minute = 2

# How long to retain an idle token bucket before evicting it from memory
bucket_ttl_secs = 3600

Changes to axon.toml take effect on daemon restart. Unlike axon_keys.json, the rate limit configuration is not hot-reloaded.

Best Practices

Use WebSocket streaming instead of polling

The /watch WebSocket stream is not rate-limited and delivers state-change events as they happen. Replace any tight GET /state polling loop with a WebSocket subscription to stay well within limits.

Batch state reads

A single GET /state call returns all state keys for an app. If your agent needs values from five fields, read them all in one request instead of five — every request counts against the same bucket.

Respect the Retry-After header

The daemon tells you exactly how long to wait. Honouring that value avoids wasting additional tokens on requests that will also be rejected.

Raise limits only for known workloads

Increase action_per_second in axon.toml only when you have profiled your agent and confirmed it genuinely needs higher throughput — lower limits reduce blast radius if agent code loops unexpectedly.

Get Started

The Daemon

Runtime Probes

Security

Guides

Default Limits by Endpoint

The 429 Response

Retry Strategy

How the Python SDK Surfaces Rate Limit Errors

Configuring Rate Limits in axon.toml

Best Practices

Use WebSocket streaming instead of polling

Batch state reads

Respect the Retry-After header

Raise limits only for known workloads

​Default Limits by Endpoint

​The 429 Response

​Retry Strategy

​How the Python SDK Surfaces Rate Limit Errors

​Configuring Rate Limits in axon.toml

​Best Practices

Use WebSocket streaming instead of polling

Batch state reads

Respect the Retry-After header

Raise limits only for known workloads

Default Limits by Endpoint

The 429 Response

Retry Strategy

How the Python SDK Surfaces Rate Limit Errors

Configuring Rate Limits in axon.toml

Best Practices