API Errors & Rate Limits

Platform API v1 returns structured JSON errors. Use status + error.code for branching — not message strings. OpenAPI documents common responses per route; this page is the cross-surface index.

Error Shape (v1)

{
  "error": {
    "code": "COOLDOWN",
    "message": "Human-readable summary",
    "details": { "retryAfterMs": 150000 }
  }
}

TypeScript: TorqueV1ErrorBody from @torquefi/types. SDK clients throw TorqueIntelligenceError (etc.) with code and statusCode.

Error Codes

HTTP	Code	Layer	Typical cause
401	UNAUTHORIZED	Auth	Missing Authorization header
401	INVALID_API_KEY	Auth	Unknown sk_live_… key
401	INVALID_TOKEN	Auth	Invalid or expired smart wallet JWT
403	BUSINESS_INACTIVE	Auth	Business account not active
403	INTEGRATOR_PRO_REQUIRED	Data	Pro integrator gate — see Entitlements guide
403	EVM_WALLET_REQUIRED	Execute	No EVM wallet on user account
403	EVM_WALLET_INVALID	Execute	Stored EVM address invalid
403	SOLANA_WALLET_REQUIRED	Execute	No Solana address on user account
400	INVALID_JSON	Request	Malformed JSON body
400	VALIDATION_ERROR	Request	Missing or invalid fields
400	BUILD_FAILED	Execute	Route builder could not construct tx
404	NOT_FOUND	READ	Resource not found (e.g. no brief available)
429	COOLDOWN	Intelligence	force=1 reroll cooldown — see details.retryAfterMs
402	assistant_credits_exhausted	Assistant	Free-tier message limit (legacy body shape)
502	JUPITER_ERROR	Execute	Solana swap upstream failure
503	CONFIG_ERROR	Platform	Server misconfiguration (e.g. Convex URL)
503	INTELLIGENCE_UNAVAILABLE	Intelligence	Feed assembly unavailable
500	INTERNAL_ERROR	Platform	Unhandled pipeline failure
500	INTELLIGENCE_ERROR	Intelligence	Generic feed error

Execute routes may return additional builder-specific codes in BUILD_FAILED messages. See Actions API and the live OpenAPI spec per route.

Rate Limits

Surface	Limit	Error	Client action
Intelligence force=1	5 min cooldown per wallet	429 COOLDOWN	Retry after details.retryAfterMs
Assistant chat (free tier)	20 messages / 30 days per wallet	402 assistant_credits_exhausted	Upgrade or wait for credit reset

General READ routes (feed, datasets, markets) do not publish global per-key rate limits today. Use exponential backoff on 503/500 from your BFF.

Retry: Intelligence Cooldown

force=1 on trade-angles (and related views) triggers a live reroll with a per-wallet cooldown. The SDK retries automatically when configured; raw HTTP clients should sleep for details.retryAfterMs.

handle-cooldown.ts

import type { TorqueV1CooldownErrorBody } from '@torquefi/types'

async function fetchWithCooldownRetry(fetchFn: () => Promise<Response>) {
  const res = await fetchFn()
  if (res.status !== 429) return res

  const body = (await res.json()) as TorqueV1CooldownErrorBody
  if (body.error?.code !== 'COOLDOWN') return res

  const ms = body.error.details?.retryAfterMs ?? 60_000
  await new Promise((r) => setTimeout(r, ms))
  return fetchFn()
}

Assistant Credits (402)

Free-tier wallets hit a message quota. The response uses a legacy top-level shape in some paths:

{ "error": "assistant_credits_exhausted", "message": "…" }

Programmatic integrators with a business key typically bypass wallet free-tier limits for server-side chat. In-app browser sessions may still be subject to credits.

Error Shape (v1)

Error Codes

Rate Limits

Retry: Intelligence Cooldown

Assistant Credits (402)

See Also