Rate Limit Contract

Throttling contract

When a request exceeds policy limits, the API returns:

• HTTP 429 Too Many Requests
• Retry-After response header
• structured body with errorCode and traceId

Example response

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

{
  "type": "https://api.uselamba.com/problems/rate-limit",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded for this tenant and route.",
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "traceId": "00-8a5f0f..."
}

Client handling

1. Parse Retry-After as seconds.
2. Back off with jitter (retry = retryAfter + random(0..2s)).
3. Retry only idempotent operations automatically.
4. Surface user-facing messaging for non-idempotent failures.

Server-side recommendations

• Keep per-tenant and per-route controls observable.
• Emit logs with errorCode, route, tenant, and traceId.
• Avoid retry storms by bounding total retry attempts.