Errors and rate limits
Every failed Developer API response is JSON and includes a request ID. Preserve that ID in your support and audit records; never include a secret key, wallet-session token, signature, or signer credential in an error report.
{
"ok": false,
"code": "wrong_network",
"message": "The wallet session is bound to a different network.",
"requestId": "req_...",
"retryable": false,
"blockedReason": "wallet_session_chain_mismatch",
"docsUrl": "https://docs.torq.finance/developers/errors/wrong_network"
}Retry rules
Rate-limit headers
Every API response carries:
x-ratelimit-limit
x-ratelimit-remaining
x-ratelimit-reset
x-request-idAnonymous discovery is limited per source IP and operation. Authenticated preview applications
receive a higher per-application operation budget, currently 120 requests per minute by default.
An application can also have scoped quotas, including sandbox and faucet quotas. Treat the headers
as authoritative rather than hard-coding a client-side limit.
Idempotency
Send Idempotency-Key for every state-changing request. Reuse it only when retrying the exact same
operation. Torq records the request fingerprint and response in the same transaction as the
mutation: a matching retry returns the safe stored result, while changed input fails with
idempotency_conflict before another write occurs.
Pagination
List endpoints that declare pagination accept the cursor and limit parameters in their OpenAPI
operation. Treat the returned pageInfo.nextCursor as opaque and preserve the API ordering while
following it. Stop when pageInfo.hasMore is false; do not synthesize an offset or sort order
from a cursor. A stale, malformed, or expired cursor fails with the returned error code and request
ID, so restart from the resource’s canonical first page when the integration cannot resume safely.
Canonical-state blocks
A workflow can be blocked because the current projected state is stale, a prior intent has not
reached final_success, a role changed, an authority was lost, or a prepared snapshot expired.
Re-fetch and re-prepare from canonical state. Do not retry a stale prepared intent or alter its
calldata locally.
Observed error-code registry
This registry is generated from the developer surface inventory. The response’smessage, blockedReason, retryable, andrequestId remain the authoritative remediation context.