Ramp Rate-Limit and Timeout Control
Overview
Coordinate all workers that share an egress IP, because independent per-process retries can amplify a rolling-window breach. Preserve idempotency and reconcile ambiguous writes before retry.
Prerequisites
- Identify the Ramp application, environment, business entities, affected data and workflows, accountable owner, and rollback boundary.
- Read
references/official-docs.mdand re-check endpoint schemas, scopes, limits, and support status before a live operation. - Use synthetic fixtures or Ramp sandbox until production access and business effects are explicitly approved.
- Prepare approved secret storage and a sanitized evidence location.
Current Contract
- Ramp currently documents a default limit of 200 requests per rolling 10-second window per source IP.
- A 429 means pause and back off; immediate retries worsen contention.
- Requests taking longer than 60 seconds terminate with 504, so large reads should be paginated and work units reduced.
- Ramp recommends exponential backoff; actual throughput is lower than theoretical throughput and endpoint constraints still apply.
Instructions
-
Inventory all services, jobs, tenants, endpoints, and retry layers sharing each source IP; measure arrival rate, burst, latency, 429/504, and business priority.
-
Implement one shared rolling-window limiter below the documented ceiling, with reserved capacity for interactive or recovery traffic.
-
Use bounded exponential backoff with full jitter for 429, 5xx, and safe 504 cases; cap attempts and total elapsed time.
-
Retry reads freely within budget, but retry writes only with an endpoint-supported idempotency key and post-timeout reconciliation.
-
Reduce pages or query scope for 504s, canary concurrency changes, and request a vendor increase only with measured demand and completeness evidence.
Tool Discipline
- Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
- Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
- Use Read to inspect the smallest required local files and authoritative evidence.
- Use Write only for a new approved local draft, test, configuration, or evidence artifact.
- Use Edit only for a bounded approved change with a known rollback.
- Local file tools do not authorize a Ramp operation or replace owner approval.
Approval Boundaries
Platform owners approve budgets and retry policy; business/finance owners approve write replay; Ramp must approve any limit increase.
Output
A shared-egress inventory, limiter design, retry matrix, idempotency policy, benchmark, canary outcome, dashboards, and vendor increase evidence if needed.
Error Handling
| Condition | Response |
|---|---|
| 429s continue below the local budget | Find other workloads sharing the egress IP and centralize their accounting. |
| A write returns 504 | Reconcile resource/task state before reuse of the original idempotency key. |
| Backoff grows queue lag | Prioritize by business criticality, shed nonessential polling, and preserve durable checkpoints. |
Examples
Example 1
Coordinate three sync workers behind one NAT with a shared rolling limiter and jittered retries.
Example 2
Recover a 504-prone historical seed by reducing page scope and committing each page before cursor advance.
Validation
- Aggregate egress stays below the re-verified current limit during load tests.
- Retry budgets are bounded and observable.
- Ambiguous writes cannot create duplicate financial effects.
- 429/504 reduction does not hide missing pages, stalled queues, or reconciliation gaps.
Resources
- Official documentation and contract notes
- Re-check the dated contract and current OpenAPI schema before any live request.
- Treat unresolved vendor behavior, authority, or financial state as a stop condition.