API Rate Limits & Authentication Guide

Secure, scalable, and predictable. Learn how to authenticate with the Aevum Encyclopedia API, understand tiered rate limits, handle throttling gracefully, and implement production-ready request patterns.

Overview

The Aevum API enforces authentication and rate limiting at the edge to protect infrastructure integrity and ensure fair usage across all clients. Proper implementation prevents downtime, reduces latency, and maintains high availability for global readers.

Authentication is handled via API keys or OAuth 2.0 bearer tokens. Rate limits are applied per key/token combination and vary by subscription tier. Exceeding limits triggers 429 Too Many Requests responses with explicit retry guidance.

Authentication

All API endpoints require authentication. Aevum supports two primary methods:

API Keys

API keys are the simplest way to authenticate. Pass your key in the Authorization header or as a query parameter (not recommended for production).

curl -X GET "https://api.aevumenc.com/v2/articles/search?q=quantum+computing" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

OAuth 2.0

For user-delegated access or enterprise integrations, use OAuth 2.0 with PKCE. Aevum supports the Authorization Code flow with standard scopes: read:articles, write:annotations, admin:workspace.

Rate Limits

Rate limits are enforced per authenticated identity (API key or OAuth token). Limits reset on a rolling window basis. Burst allowance permits short spikes above the sustained limit.

Exceeding daily quotas returns 429 until the next UTC midnight. Sustained overuse may trigger temporary key suspension after 3 warnings within 24 hours.

Response Headers

Every API response includes rate limit headers to help clients monitor usage and implement backoff strategies.

Error Handling

Authentication and rate limit errors follow standard HTTP semantics with structured JSON payloads:

Code Examples

Python (requests)

import requests
import time

def fetch_with_backoff(url, headers, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)
        if resp.status_code == 429:
            retry_after = int(resp.headers.get('Retry-After', 5))
            print(f\"Throttled. Waiting {retry_after}s...\")
            time.sleep(retry_after)
            continue
        return resp.json()
    raise Exception(\"Max retries exceeded\")

headers = {\"Authorization\": \"Bearer YOUR_API_KEY\"}
data = fetch_with_backoff(\"https://api.aevumenc.com/v2/articles/quantum\", headers)

JavaScript (Fetch)

async function fetchWithRetry(url, options = {}) {
  const maxRetries = 3;
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, options);
    if (res.status === 429) {
      const retryAfter = res.headers.get('Retry-After') || '5';
      console.log(`Rate limited. Retrying in ${retryAfter}s...`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }
    return res.json();
  }
  throw new Error('Max retries exceeded');
}

fetchWithRetry('https://api.aevumenc.com/v2/articles', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

Best Practices

• Cache aggressively: Article content rarely changes. Use ETag and Cache-Control headers to avoid redundant fetches.
• Implement exponential backoff: Base delay of 1s, doubling per retry, with jitter to prevent thundering herds.
• Monitor headers: Log X-RateLimit-Remaining to predict quota exhaustion before it impacts users.
• Rotate keys regularly: Generate separate keys for production, staging, and development. Revoke unused keys immediately.
• Use connection pooling: HTTP/2 and keep-alive reduce TLS overhead and improve throughput within concurrency limits.

FAQ

How can I increase my rate limits?

Upgrade to the Pro tier for 10x sustained throughput, or contact Enterprise Sales for custom allocations, dedicated endpoints, and SLA guarantees.

What happens when I exceed the limit?

You receive a 429 response with a Retry-After header. Requests are safely rejected without queuing. No data is lost, and your key remains active unless repeatedly violated.

Are rate limits shared across subdomains?

No. Each API key/token is scoped to a specific environment (api.aevumenc.com, eu.api.aevumenc.com, etc.). Limits are calculated independently per region.

Can I get usage analytics?

Yes. The Developer Dashboard provides real-time request graphs, quota utilization, geographic distribution, and endpoint popularity. Export CSV/JSON or subscribe to billing-cycle reports.