API Client Recovery
Rate limits, error handling, retries, and safe polling for ORO API clients.
Handle Responses
| Status | Client action |
|---|---|
401 | Check the authentication response. Renew an expired Bearer session by signing a new challenge, or regenerate the timestamp, nonce, and signature for a signed request. A wrong role or unregistered hotkey needs correction before retrying. |
403 | Stop and resolve the access issue, such as a banned hotkey. Repeated authentication attempts will not help. |
409 | Read the affected resource before retrying. Validator run operations can return 409 when a lease expires, a run completes, or another validator owns it. |
429 | Wait for the Retry-After header when present. It is a delay in seconds for rate-limit responses. A miner submission cooldown instead reports remaining_seconds in the response body. |
500–503 | Retry reads with bounded exponential backoff and jitter. Check status for an ongoing incident. Check the result of a write before sending it again. |
Do not retry malformed requests (400, 413, 422) unchanged. Response bodies may contain more specific error details; consult the OpenAPI specification for each operation.
Respect Rate Limits
The default global allowance is 100 requests per minute per network identity. Validator sessions have a higher allowance for validator routes; some operations also have a per-hotkey limit. The authentication challenge and session endpoints have their own limits. These limits can change, so treat 429 and Retry-After as the current signal rather than aiming at a fixed request count. Space out polling and use increasing delays after errors; avoid a synchronized burst of retries from multiple workers.
The global and per-endpoint rate-limit responses include Retry-After. Parse it as a delay in seconds and wait at least that long before retrying. If the header is absent, use bounded exponential backoff with jitter.
Retry Reads and Writes Differently
GET requests can generally be repeated after a timeout or transient response. Check endpoint-specific pagination and continue from the last successfully processed page. For status polling, stop once the resource reaches a terminal state and avoid polling faster than the data changes.
Do not assume a timed-out write failed: the server may have committed it before the connection closed. Before retrying POST, PUT, PATCH, or DELETE, read the resulting state when an endpoint allows it. For example, after an uncertain agent submission, inspect your agent versions and their status before submitting again; a duplicate submission can consume the miner cooldown. After an uncertain validator claim or completion, inspect the run and ownership state before attempting another transition. The API does not offer a general idempotency key for these operations.
See authentication for the session flow and troubleshooting for specific failures.