Errors, limits and safe retries

Every error code with its HTTP status and whether to retry, the limits behind them, and how to retry without duplicating work.

Updated 2026-10-22

Every refusal from the /v1 API names a code from one closed list, says whether the same request may be sent again, and keeps the work you already paid for safe. This page lists every code, the limits behind them, and how to retry without starting the same work twice.

Handle an error

1. Check the HTTP status. A failure in front of the service can be non-JSON.
2. Read error.code and error.retryable. Never branch on error.message; it is for people.
3. If retryable is true, wait error.retry_after_s when it is present, then send the identical request with the same request_id.
4. If retryable is false, fix the cause from the table below. Then send the work with a new request_id.
5. If you don't know whether the request arrived (a network error, your own timeout, a 5xx), read the original before you send anything new. See Keep request identity stable.

Treat a code you don't recognize as final unless retryable is true.

The error object

Every /v1 reply is the envelope {ok, data, error, job, cost, hints}. A refusal has ok: false, data: null and:

{"code": "rate_limited", "message": "too many requests for this credential",
 "retryable": true, "retry_after_s": 0.4, "details": {"limit": "credential_rate"}}

A 401 also carries WWW-Authenticate: Bearer realm="wavemaker", with the OAuth protected-resource metadata for MCP hosts.

Codes

Why a delivery was refused

not_deliverable carries details.reason:

Errors outside the /v1 envelope

Errors inside a running turn

Failures while the hosted agent works, such as a provider error or a refused tool call, are the agent's to handle. They appear as tool.completed events with ok: false and error_code; the turn carries on.

• A tool call or model call refused for money ends the turn completed with outcome.status partial or stopped and reason: "budget". What was made is kept.
• A turn whose agent doesn't start within 120 seconds, or stops answering for 180 seconds, ends failed with a retryable timeout.
• A turn ends failed only when it can't continue. Retry it as a new turn with a new request_id.

Limits

A turn posted behind its own session's running turn queues instead of counting toward the workspace's running turns.

Timeouts and waiting

Set your client's timeout above the wait you ask for; 100 seconds covers every wait_s above. A timeout on your side stops your observation, not the work. It never cancels a job or a turn.

Keep request identity stable

A request_id names one piece of work. Choose it before you send, save it, and reuse it only for that work.

• Same id, same body: a replay. You get the original outcome, and nothing runs or is charged twice. Session replies carry Wavemaker-Replayed: true.
• Same id, different work: request_id_mismatch on the session API, request_conflict on the tools. Nothing starts.
• Uncertain outcome: after a network error, your own timeout or a 5xx, resend the identical request with the same id, or read the original (GET /v1/sessions/{id}/requests/{request_id}, or read of the job). Never invent a new id for the same work.
• Retryable refusal (rate_limited, busy, policy_unavailable, timeout, sandbox_unavailable): nothing was recorded. Retry with the same id after retry_after_s.
• Recorded refusal of a session turn (insufficient_credits, cap_exceeded, quote_expired, policy_refused, consent_required): a replay returns the same error. Fix the cause and use a new id.
• Work that ended `failed`: the id keeps returning that failure. Retry as new work with a new id.

Session request_ids match ^[A-Za-z0-9._:-]{1,200}$. Tool calls don't change a job's identity when only max_microcredits, quote_id, rush or wait_s change.

Separate watching from stopping

A wait that ends with nothing new means you stopped watching. It doesn't mean the job failed, and it cancels nothing.

• To stop a job: write with {"uri": "wm://job/{id}", "cancel": true}.
• To stop a session turn: POST /v1/sessions/{id}/interrupt.
• To end a session: POST /v1/sessions/{id}/close.

See Quote and run work for job states and Recover interrupted work for the web app.

Related guidance

• Understand credits, reservations and charges
• HTTP API
• Quote and run work
• Make an ad through the session API
• Recover interrupted or uncertain work