Rate Limits

HarborGuard enforces sliding-window rate limits on the endpoints that are most expensive to back. Limits run after authentication and before plan-limit checks, so unauthenticated traffic never consumes quota.

Limits per endpoint family

The window is one minute unless noted. Buckets key on the calling client IP, so a single IP shares the bucket across credentials.

Read-only endpoints (GET) and resource-detail mutations (PUT, DELETE) are not rate-limited at the API layer; they are bounded by your plan's monthly quota and fair-use protections.

429 response

When a request would exceed its limit, HarborGuard returns 429 Too Many Requests:

HTTP/1.1 429 Too Many Requests
Retry-After: 27
Content-Type: application/json
 
{ "error": { "code": "RATE_LIMITED", "message": "Too many requests" } }

The Retry-After header is in seconds and reflects the time remaining until the current window resets. Clients should respect it before retrying.

Plan limits vs. rate limits

Rate limits cap requests per minute; plan limits cap resources per billing period (number of scans, registries, members). Plan-limit failures are surfaced separately:

{ "error": { "code": "PLAN_LIMIT", "message": "Scan limit reached for current plan" } }

with HTTP 402 Payment Required. Upgrade your plan from Settings → Billing or remove unused resources.

Best practices

• Use one credential per workload so noisy-neighbor bursts don't poison shared buckets.
• Implement exponential backoff with jitter when retrying a 429.
• Cache list responses on the client when polling; use meta.total as a cheap change indicator.
• For high-volume scan kickoff, prefer registry-level scheduling over per-image POSTs.