Errors and limits

Error envelope

1234567{
    "error": {
        "code": "account_disabled",
        "message": "The connected account is disabled",
        "requestId": "6c9e4a3e-..."
    }
}

Error codes

Retries

• capacity_exhausted returns 503 with a bounded Retry-After header. Honor it. Planned image rollouts keep resident sessions serving and create current-image overlap capacity only when authenticated migration or new-account demand needs it. The default physical peak is POOL_MAX_RUNTIMES + 1. Operators may raise POOL_ROLLOUT_MAX_SURGE_RUNTIMES only after measuring peak host fit, up to a maximum of POOL_MAX_RUNTIMES; the configurable physical maximum is twice the base runtime count. Migration reservations remain exclusive; new accounts use unreserved capacity, with at most one eligible oldest-idle eviction per admission at saturation or bounded backpressure. Accounts migrate directly to the current image using the request's credentials; idle sessions keep the existing five-minute TTL, spare-slot renewal, and six-hour cap. Current-image sessions on excess runtimes never migrate just to shrink the fleet. Placement fills base runtimes first. After the rollout, new accounts use only that base, and excess runtimes retire only when empty after normal closure or idle expiry. Requests for an existing excess account can prolong its residency. An empty stale runtime stays ready until a current-image successor is ready, except at an all-stale physical ceiling where full base readiness remains after retirement. Host refusal or the surge ceiling stalls progress and logs bounded deferrals while existing sessions keep serving. Creation retries use 5-to-60-second transient backoff or terminal 300-second re-probes. Readiness reports rollout progress separately, including surge state, optional current and maximum surge counts, waiting, and last failure class/time. It exposes no credentials, account identity, or target digest. Fresh-session replacement cancels its successor; shutdown aborts rollout work before releasing authority. Normal account capacity, admission bounds, serving/attaching protections, and first-service grace still apply.
• rate_limit_exceeded returns 429 with Retry-After and the current rate-limit headers.
• subscription_required returns 402; start or restore the subscription in the control surface.
• control_plane_unavailable returns 503 with Retry-After for control-plane transport failures including a broken response body at any status, upstream timeouts, HTTP 429 or non-560 HTTP 5xx responses, and Convex service-unavailable responses. Structured ConvexError and other application failures stay application errors; unstructured Convex Server Error HTTP 560 retains its transient classification, and FiveSocket's own response deadline remains request_timeout. Convex 429 preserves a valid upstream Retry-After up to the shared 300-second API bound, otherwise the delay is one second. It is not retried internally. Other transport-failed reads are retried once internally first; trading and account mutations are not. No trading command was dispatched, so it is safe to repeat the same request with the same idempotency key. If a dispatch-marker, warming-defer, or execution-result write cannot be confirmed, or the command already owned by another dispatch attempt cannot be read, the response is a 202 command with outcome: commit_unknown instead, and the command resolves through the command poll.
• A request that begins serving but exceeds its deadline returns 504. The worker session is fenced and destroyed, so the read either fully happened or fully did not.
• Client mistakes return 4xx and are never worth retrying unchanged.

Idempotency

Pagination

• initial reads require an explicit to; missing it returns 400 invalid_request
• from defaults deterministically to 30 days before to
• cursor requests omit from and to because the cursor carries both bounds
• the window cannot exceed 90 days
• limit is 1 to 1000, default 100

Limits

• request rate and concurrent requests
• concurrent logins per account
• maximum trade-history interval and page size
• maximum request deadline
• request bodies over 32 KB are rejected