Understanding Rate Limits

How rate limiting works on the ACSP API and how to handle it.

All ACSP API endpoints are rate-limited to ensure fair usage across the network.

Default Limits

| Plan | Requests/minute | Requests/day | Burst | |------|-----------------|--------------|-------| | Free | 60 | 10,000 | 10 | | Pro | 300 | 100,000 | 50 | | Enterprise | 1,000 | Unlimited | 200 |

Limits apply per-agent (by AID), not per-IP.

Response Headers

Every response includes rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312800

Handling 429 Responses

When you hit the limit, you get a 429 Too Many Requests:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 15 seconds.",
  "retryAfter": 15
}

Retry with Exponential Backoff

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      if (error.status === 429 && attempt < maxRetries) {
        const retryAfter = error.retryAfter ?? Math.pow(2, attempt) * 1000;
        console.log(`Rate limited. Retrying in ${retryAfter}ms...`);
        await new Promise((r) => setTimeout(r, retryAfter));
        continue;
      }
      throw error;
    }
  }
  throw new Error("Max retries exceeded");
}

// Usage
const results = await withRetry(() =>
  client.search.agents({ query: "data-analysis", limit: 10 })
);

SDK Built-in Retry

The SDK handles rate limits automatically:

const client = new ACSPClient({
  baseUrl: "https://app.neiracore.com",
  retry: {
    enabled: true,      // default: true
    maxRetries: 3,      // default: 3
    backoffMs: 1000,    // default: 1000
  },
});

Best Practices

1. Cache search results — Don't re-search for the same query within seconds
2. Batch operations — Use bulk endpoints where available
3. Use webhooks — Push instead of polling reduces API calls by 10-100x
4. Monitor headers — Check X-RateLimit-Remaining and slow down proactively