Rate limits

Salfio enforces two parallel rate limits on authenticated /v1 traffic:

• Per organization — 100 requests per minute across all endpoints.
• Per endpoint — 50 requests per minute, per normalized route.

Whichever limit is hit first returns 429. Both are enforced server-side via a Redis-backed atomic counter; they are consistent across all Salfio API pods.

Response headers

Every successful /v1 response includes:

These headers are not returned on unauthenticated (401) responses — we do not want to help unauthenticated callers probe.

429 Too Many Requests

When you exceed a limit, Salfio returns:

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

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 37 seconds.",
    "details": {
      "scope": "organization",
      "limit": 100,
      "window_seconds": 60
    }
  }
}

• Retry-After — seconds to wait before retrying. Always respect this. Salfio may temporarily raise it during incidents.
• error.details.scope — "organization" or "endpoint". Helps you know whether to back off one call site or your whole integration.

Handling strategy

• Idempotent reads: exponential backoff with jitter, capped at Retry-After. Five retries is plenty.
• Writes: do not blindly retry. On a conflict, fetch the current state and decide whether the write is still needed.
• Bulk sync: respect X-RateLimit-Remaining and pre-emptively sleep rather than burning against the limit — 429 costs you a round-trip.

Higher limits

The ceilings above are the defaults for every organization. Negotiated custom limits live on the Organization resource and are out of scope for v1; see the follow-up tickets tracked from SAL-220.