Rate Limit Contract

Contract

When a request exceeds limits, Lamba returns:

• 429 Too Many Requests
• Retry-After header
• structured JSON error with errorCode and traceId

Example

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 workspace, client, or route.",
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "traceId": "00-8a5f0f..."
}

Retry-After handling

• Parse Retry-After as seconds.
• Wait at least Retry-After before retrying.
• Add jitter to avoid synchronized retries.

Safe retry policy

• Auto-retry only idempotent operations.
• Use exponential backoff with bounded retries.
• Suggested max: 3 retries for synchronous traffic.
• Stop retrying early on repeated 429 with long Retry-After windows.

Server/client guidance

• Clients should surface user feedback for non-idempotent failures.
• Services should include traceId in logs for throttled requests.
• Auth flows may throttle by IP and identifier together; admin APIs may throttle by workspace and client together.