Default limits

Rate limit headers

Every Atlas API response includes headers describing the current limit state. Monitor these to implement proactive backoff before hitting 429s.

X-Atlas-RateLimit-Limit: 300
X-Atlas-RateLimit-Remaining: 247
X-Atlas-RateLimit-Reset: 1716291660
X-Atlas-RateLimit-Reason: runtime-org-rate
Retry-After: 12
X-RateLimit-Remaining: 247

Handling 429 Too Many Requests

When a request is rate-limited, the API returns 429 Too Many Requests with aRetry-After header. Implement exponential backoff starting at 1 second, doubling on each subsequent 429, up to a maximum of 32 seconds.

async function atlasRequestWithBackoff(fn, retries = 5) {
  for (let i = 0; i < retries; i++) {
    const res = await fn();
    if (res.status !== 429) return res;
    const retryAfter = parseInt(res.headers.get("Retry-After") ?? "1");
    await new Promise(r => setTimeout(r, retryAfter * 1000 * Math.pow(2, i)));
  }
  throw new Error("Rate limit retries exhausted");
}

Webhook delivery guarantees

Atlas delivers webhook events at-least-once. Your handlers must be idempotent. If your endpoint returns a non-2xx response, Atlas retries with exponential backoff over 24 hours. Unique event IDs are provided so duplicate detection can be implemented server-side.

POST /v1/atlas/webhooks
{
  "url": "https://your-server.com/atlas/events",
  "events": ["conversation.created", "message.delivered", "agent.handoff"],
  "secret": "whsec_your_signing_secret"
}
Response: { "webhook_id": "wh_01HX9Z", "status": "active" }

Best practices

• Always read X-Atlas-RateLimit-Remaining before issuing burst traffic; throttle proactively at 20% remaining.
• Prefer webhook subscriptions over polling for high-frequency event consumers.
• Use separate service accounts for independent subsystems to avoid one subsystem exhausting shared org limits.
• Cache expensive read responses (e.g., tool manifest, knowledge corpus) locally rather than refetching on every request.
• For bulk operations, batch requests and respect the bulk ingest limit of 10 jobs per minute.