Rate Limits

TL;DR

Athena gates request volume through three independent layers:

1. Pre-auth IP shield — hardcoded 20 req/60s per IP on /auth/*. Stops credential-stuffing.
2. Configurable rate limits — workspace admins author rules scoped to Agent, Customer, API Key, or Workspace. Enforced on every authenticated request.
3. System guards — workflow timeout, recursion cap, budget, webhook concurrency, push-notification dedup. Hardcoded constants in the engine.

When a limit fires, the API returns 429 Too Many Requests with RFC 9239 headers plus Retry-After.

Scopes

Rules are evaluated from most-specific to least-specific:

Scope	What it limits
Agent	Calls to one specific agent
Customer:product	Customers holding a specific subscription product
Customer:paid	Any paid customer
Customer:free	Any customer without an active subscription
Customer:*	All customers regardless of tier
User (API key)	One API key (wak_ or eak_)
Workspace	Total workspace traffic

Time Windows

Second, Minute, Hour, Day, Week, Month, BillingCycle.

Note

BillingCycle is only valid for Customer-scoped rules. It is backed by RevenueCat expires_at for subscribed customers, or a fixed 24h synthetic cycle anchored to customer creation when there is no active subscription.

Limit Types

• Requests — count of API calls
• Tokens — LLM tokens (prompt + completion combined)
• Cost — accumulated cost in microdollars (1 USD = 1,000,000 microdollars)

429 Response

HTTP/1.1 429 Too Many Requests
Retry-After: 42
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 42
RateLimit-Policy: 100;w=60;scope=workspace
RateLimit-Scope: workspace:requests

{
  "error": {
    "code": "rate_limit_requests_exceeded",
    "message": "Request limit exceeded. Try again in 42 seconds.",
    "details": {
      "limit": 100,
      "current": 100,
      "reset_in_seconds": 42,
      "window": "minute",
      "scope": "workspace"
    }
  }
}

Error Codes

Code	Meaning
rate_limit_requests_exceeded	Request count limit hit
rate_limit_tokens_exceeded	Token usage limit hit
rate_limit_cost_exceeded	Cost budget limit hit
rate_limit_anonymous_abuse	Pre-auth IP shield triggered

What to Do When Rate Limited

1. Read Retry-After from the response header. Wait that many seconds before retrying.
2. Implement exponential backoff for repeated 429s.
3. For token/cost limits, use POST /agents/{id}/preview-credits to estimate cost before executing.
4. Contact your workspace admin to adjust limits if your use case legitimately exceeds the defaults.

System Guards (Non-Configurable)

These limits are hardcoded and cannot be changed via the API:

Guard	Limit
Pre-auth IP	20 req / 60s
Login throttle (per email)	5 / 15 min
Token exchange (per IP)	10 / min, 50 / hr
WebSocket connections (global)	100
Conversation turn lock	1 in-flight per conversation
Request body size	2 MiB
Workflow timeout	300s default
Workflow recursion	25 node visits
Workflow output	50 MB
HTTP tool timeout	30s default, 60s max
Webhook delivery concurrency	20 in-flight
Push notifications (per customer)	10 / hr + 60s dedup