Timeouts and retries - Onecortex

How long a call can run

A call runs as long as your agent takes, up to the life of its session’s instance: an hour at most. There is no shorter limit on a single call. Your client is usually the limit that matters. Most HTTP clients give up on a response that sends nothing for a while, and a proxy in front of your app may do the same.

Stream long calls. With "stream": true, Onecortex sends a : ping comment every 15 seconds while your agent is silent, so the connection never looks idle.
Set your client’s read timeout above 15 seconds, or turn it off, for a streamed call. httpx’s default is 5 seconds.
A JSON call sends nothing until the run ends, so its read timeout has to cover the whole run.

Onecortex never retries a call

A call reaches your agent once. If it fails, Onecortex does not call your agent again, so a tool with side effects, such as sending an email or charging a card, runs once per request you make. Whether to retry is yours to decide, with that in mind.

What to retry

Status and code	Retry?
`429` `rate_limited`	Yes, after the `Retry-After` header’s seconds
`503` `agent_unavailable`, `service_unavailable`, `capacity_exceeded`	Yes, with backoff
`502` `upstream_error`	Yes, with backoff, unless the message says to redeploy
`409` `agent_not_ready`	Yes, once the first build succeeds
`500` `internal_error`	Once or twice; then send the `requestId` to support
`502` `agent_error`	Only if your agent’s failure is transient: it is your code that raised
`400`, `401`, `403`, `404`, `409` `agent_not_deployed`, `410`, `413`	No. The request or the setup is wrong, and the same call fails the same way

An event: error in a stream carries the same codes, and the same advice applies. Back off exponentially from about a second, with jitter, and stop after a few attempts. Every response carries X-Request-Id: log it, so a failure can be matched to your agent’s logs and to support.

Rate limits

Calls are limited per organization and per agent. See Limits. A retry loop that ignores Retry-After spends the budget faster and fails for longer.

Last modified on September 28, 2026