API rate limits

The Penaxtra public API enforces per-token rate limits to keep the platform fair across customers + to stop a runaway script from amplifying cost.

Defaults

• 60 requests per minute per token (sustained)
• 120 requests burst allowance (token bucket refills at 1 RPS)

Specific routes carry tighter caps:

Response headers

Every authenticated response carries the current bucket state:

• X-RateLimit-Limit - sustained ceiling for the route
• X-RateLimit-Remaining - tokens left in the bucket
• X-RateLimit-Reset - seconds until the bucket refills

429 handling

When the bucket is empty:

HTTP/1.1 429 Too Many Requests
Retry-After: 17
Content-Type: application/json

{
  "error": "rate_limited",
  "retry_after_seconds": 17,
  "limit": 60,
  "window": "1m"
}

Honour the Retry-After header. Penaxtra never penalises a client that backs off cleanly; clients that ignore Retry-After and re-fire immediately are auto-cooled with an exponential penalty.

Per-workspace ceiling

In addition to per-token limits, every workspace has a per-minute ceiling across ALL tokens. Defaults:

Long-running operations

Scans and reports are asynchronous. The POST returns immediately with a queued or running state; pollers should use the per-resource GET endpoint at most every 10 seconds. Webhooks are the preferred pattern for high-volume integrations.

Security notes

• Rate-limit decisions live in a short-TTL in-memory key-value store; restart-safe.
• Rate-limited responses are NOT counted against the per-token bucket (no compounding penalty).
• A 429 with retry_after_seconds = 0 indicates a circuit-breaker condition (the route is temporarily disabled platform-wide); back off for at least 60 seconds.

Related

• API authentication
• Findings API
• Reports API

Last reviewed: 2026-06-13. Reviewed by: Engineering. Content type: Developer documentation. Reach the maintainers: [email protected] .