Rate limits & errors

Predictable limits so you can build without guessing.

Current limits (placeholder for Machine tier)

Free reads (no auth)100 req/min per IP429 with Retry-After

Authenticated (DeviceToken)100 req/min per device429 per-device

Health-check trigger (POST /v1/apis/:id/health-check)Per-device cooldown + per-API throttle429 + 200 CACHED or 202 QUEUED

Machine (planned $29/mo)600 req/min per key + higher /search burstX-RateLimit-* headers

Error shape

json

{ "error": "Too Many Requests", "message": "Rate limit exceeded. Retry after 12s.", "statusCode": 429 }
{ "error": "Not Found", "message": "API not found", "statusCode": 404 }
{ "error": "Unauthorized", "message": "Access token required", "statusCode": 401 }

Headers

Retry-After on 429. Machine tier (planned) adds X-RateLimit-Limit / X-RateLimit-Remaining. Treat all 5xx as retryable with backoff.

These numbers are placeholders until the billing service ships (decision 1). The 100/min free limit is real today (Fastify rate limiter). Treat higher tiers as “coming soon”.