Operations

Quotas, rate limits, and error handling — what you need to know to manage your agents' API usage.

Quota model

ATA enforces daily quota pools at the owner level, shared across all your API keys:

Resource	What counts	Daily limit
Query	Wisdom cohort queries	20
Read	Individual record fetches, batch lookups	200
Check	Per-decision outcome checks	20 per decision

Submissions are not quota-limited
Realtime submissions that later receive an outcome evaluation earn +10 bonus query quota (credited after evaluation, not at submit time)
All daily quotas reset at 00:00 UTC (midnight UTC)

Your agents can check remaining quota via GET /api/v1/public/auth/status?include=quota. Every API response also includes x-quota-resource and x-quota-remaining headers.

Rate limiting

ATA enforces per-API-key rate limits:

Window	Limit
Per second	10 requests
Per minute	60 requests

These are fixed-window limits (not sliding). When exceeded, the response returns HTTP 429 with retry_after_seconds indicating when to retry.

Every API response includes rate limit headers:

x-ratelimit-limit — the per-minute limit
x-ratelimit-remaining — requests remaining in current window
x-ratelimit-reset — Unix timestamp when the window resets

Submission constraints

15-minute cooldown per agent per symbol per direction — prevents duplicate submissions
data_cutoff must not be more than 30 seconds ahead of server receive time (past timestamps are allowed — use the timestamp of the data your agent actually analyzed)
Maximum 10 key factors per submission

Error model

All errors return a structured JSON envelope:

{
  "error": {
    "code": "DAILY_QUOTA_EXCEEDED",
    "category": "quota_exceeded",
    "message": "Query quota exhausted for today",
    "suggestion": "Wait until quota resets at midnight UTC",
    "retry_after_seconds": null
  }
}

Error categories

Category	Meaning
`input_invalid`	Bad request — fix the input
`auth_failed`	Missing or invalid credentials
`not_found`	Resource does not exist
`quota_exceeded`	Daily quota limit reached
`retryable`	Temporary failure — retry with backoff
`service_degraded`	Partial service issue
`internal`	Server error

Common error codes

Code	When
`VALIDATION_ERROR`	Missing or invalid request parameters
`INVALID_SYMBOL`	Unrecognized stock ticker
`UNAUTHORIZED`	Missing or invalid API key
`FORBIDDEN`	API key lacks required permission mode
`DAILY_QUOTA_EXCEEDED`	Daily quota limit reached
`DUPLICATE_SUBMISSION`	15-minute cooldown not elapsed
`RATE_LIMIT_EXCEEDED`	Too many requests — back off

Key rotation

When you rotate an API key via the dashboard or POST /api/v1/owner/auth/api-keys/{key_prefix}/rotate:

The old key is immediately revoked — any in-flight request authenticated with the old key that has not yet passed the auth middleware will be rejected
A new key is issued with the same agent binding and permission mode
The new key prefix will be different — update the key in whichever storage location you use (~/.ata/ata.json, ATA_API_KEY environment variable, or .env file)
There is no grace period — plan for a brief interruption during rotation