Overview
Prefer the CLI's built-in 429 retry for ordinary commands and add one orchestration-level call budget around it. For direct REST clients, implement capped backoff because the API does not return standard rate-limit headers.
Prerequisites
- Endpoint and HTTP-method inventory with expected call volume
- Single owner for retry count, polling interval, deadline, and concurrency
- Metrics for calls, 429s, latency, cached hits, and abandoned work
Instructions
Step 1: Map the identity boundary
Group calls by endpoint, method, bearer token, session user, query key, and client IP because each can contribute to the enforced identity.
Step 2: Choose one retry layer
For CLI commands, configure --retry and do not wrap them in another exponential retry. For REST, retry only 429 with a capped backoff and total deadline.
Step 3: Replace tight polling
Cache stable offer and account data, poll only resources still in transitional states, stop on terminal states, and progressively lengthen the interval.
Step 4: Flatten bursts
Queue work, spread scheduled jobs, and batch operations where the documented endpoint supports it. Bound concurrency per endpoint.
Step 5: Honor the call budget
Stop when attempts, elapsed time, or request count reaches the approved ceiling; surface a retryable operational result instead of looping.
Step 6: Escalate sustained pressure
Report endpoint, identity shape, measured call rate, 429 rate, and business need to support when production volume requires a higher limit.
Authentication
Use the narrowest key for each worker and never rotate keys merely to evade a limit. Redact tokens and query credentials from request and retry logs.
Tool Discipline
Use Read and Grep to inspect manifests, configuration, provider output, and existing tests before proposing a mutation. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not create, update, destroy, or fund Vast.ai resources without explicit operator approval.
Output
- Endpoint/identity traffic inventory
- Retry, polling, caching, concurrency, and deadline policy
- Measured before/after call volume and 429 receipt
Return endpoints, identity partition, client type, retry owner, call ceiling, observed 429s, elapsed time, and final disposition.
Examples
A readiness watcher uses one CLI command with --retry 3, polls only while state is transitional, lengthens the interval, and exits immediately on running, exited, unknown, or offline.
Error Handling
| Failure | Response |
|---|---|
| REST response is 429 | Back off within the total deadline; do not expect Retry-After. |
| Non-429 4xx occurs | Do not retry automatically; repair arguments, authentication, or permission. |
| Retry layers multiply | Remove the outer retry or disable the inner one so only one owner controls attempts. |
| Deadline expires | Return the last state and next safe action without another call. |