Rate limits

Request quotas and how to handle them.

Requests are rate limited per organization (keyed by your API key).

Scope	Limit
All /api endpoints	100 requests / 60 seconds
POST /api/payments/initiate	10 requests / hour

Response headers

Every response includes:

Header	Meaning
X-RateLimit-Limit	Max requests in the window.
X-RateLimit-Remaining	Requests left in the current window.
X-RateLimit-Reset	Unix time when the window resets.

When you exceed a limit

You get 429 RATE_LIMIT_EXCEEDED:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "details": { "limit": 100, "retryAfter": 42 }
  }
}

Back off and retry after details.retryAfter seconds.

Tips

• For bulk work, use list endpoints with filters (e.g. GET /api/payouts?status=PROCESSING) instead of many per-item calls.
• Use bulk import for onboarding many farmers/plots at once (POST /api/farmers/bulk-import) rather than looping register.
• Add jitter to polling intervals so retries don’t synchronize.