Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

docs(sdk-go): document write retry migration

JasonBuildAI1d7c63369d62
diff --git a/docs/sdks/go.md b/docs/sdks/go.md
index c5bc01faa..152d54a86 100644
--- a/docs/sdks/go.md
+++ b/docs/sdks/go.md
@@ -489,6 +489,20 @@ sandbox, err := opensandbox.CreateSandbox(ctx, config, opensandbox.SandboxCreate
})
```
+### Retry policy
+
+`ConnectionConfig.Retry` and `WithRetry` retry transient failures with exponential backoff. Idempotent methods (`GET`, `HEAD`, `PUT`, `DELETE`, `OPTIONS`) retry `429`, `502`, `503`, and `504` by default. `POST` and `PATCH` retry only dial, proxy-connect, and TLS-handshake failures that are provably pre-send by default; status-code retries for writes are opt-in because a replay can duplicate a sandbox, session, command, or file mutation. Set `RetryableStatusCodesNonIdempotent` only when the operation is idempotent at the application layer or duplicate execution is acceptable:
+
+```go
+config.Retry = &opensandbox.RetryConfig{
+ MaxRetries: 3,
+ InitialBackoff: 500 * time.Millisecond,
+ RetryableStatusCodesNonIdempotent: []int{http.StatusServiceUnavailable},
+}
+```
+
+SSE bootstraps do not use the generic retry loop, even when a write status code is opted in.
+
### Wake retry
A request to a paused sandbox may arrive while its restore is still in progress. The gateway answers `503` with the `OpenSandbox-Wake: expired` marker; the client recognizes it and resends the original request after the `Retry-After` delay (safe for any method — the marker proves the request was never forwarded). The wake budget defaults to 5 attempts / 60 seconds across all wake cycles; when it is exhausted the client returns a `*SandboxWakeTimeoutError` (carrying `Attempts` and `Waited`) while the server-side resume continues in the background. Bare `503` responses follow the existing retry rules untouched. Wake retry is active whenever a `WithRetry` config is set (`WakeRetryEnabled` defaults to enabled even for hand-built configs; pass `WakeRetryDisabled()` to opt out); streaming connections bypass wake retry — a waking sandbox fails fast with the marked 503 instead of parking the connect — matching the other official SDKs, and established streams are never re-executed.
diff --git a/sdks/sandbox/go/config.go b/sdks/sandbox/go/config.go
index 93a5b1693..a6acbbb46 100644
--- a/sdks/sandbox/go/config.go
+++ b/sdks/sandbox/go/config.go
@@ -59,9 +59,11 @@ type ConnectionConfig struct {
AuthHeader string
// Retry enables automatic retry with exponential backoff for transient
- // errors. Defaults to retrying 429/502/503/504; override
- // RetryConfig.RetryableStatusCodes for custom policies. If nil, requests
- // are not retried.
+ // errors. Idempotent methods default to 429/502/503/504; override
+ // RetryConfig.RetryableStatusCodes for custom idempotent policies. POST
+ // and PATCH do not retry status codes unless listed in
+ // RetryConfig.RetryableStatusCodesNonIdempotent. If nil, requests are not
+ // retried.
// Use DefaultRetryConfig() for sensible defaults.
Retry *RetryConfig