Handle API errors

All Sandbox API errors use the same JSON envelope:

{
	"error": {
		"code": "idempotency_conflict",
		"message": "This Idempotency-Key is already attached to a different request"
	}
}

Error reference

HTTP	Code	Meaning	Action
`400`	`invalid_json`	The request body is not valid UTF-8 JSON.	Correct the JSON before retrying.
`400`	`invalid_request`	A field or event-feed query failed validation.	Send only the documented fields and constraints.
`401`	`unauthorized`	The bearer key is missing, malformed, revoked, or inactive.	Replace it with an active key.
`403`	`insufficient_scope`	The key does not include the capability required by this route.	Mint a key with the required scope.
`403`	`membership_required`	The grant user is no longer a live member of the bound organization.	Restore membership or use another grant.
`404`	`not_found`	The resource is invalid or not visible to this access grant.	Check its ID and the authenticated grant.
`409`	`idempotency_conflict`	An idempotency key already has different request details.	Use the original details or a new idempotency key.
`409`	`idempotency_in_progress`	The original sandbox creation has not materialized yet.	Retry the same request and key after a short delay.
`409`	`concurrency_limit_exceeded`	Starting or restarting a sandbox would exceed the grant limit.	Wait for another sandbox to finish.
`409`	`sandbox_not_running`	The command requires a running sandbox or active turn.	Reconcile state, then retry when applicable.
`409`	`interrupt_pending`	An interrupt is already durably queued.	Observe the stream instead of submitting another.
`402`	`no_credits`	The bound organization cannot reserve another inference run.	Add credits before creating or restarting a sandbox.
`413`	`request_too_large`	The request body exceeds the route’s 16 KiB or 64 KiB limit.	Reduce the body before retrying.
`413`	`file_too_large`	The requested sandbox file exceeds the 100 MiB download limit.	Fetch the file another way or trim it.
`415`	`unsupported_media_type`	The request does not use `application/json`.	Set the correct `Content-Type`.
`400`	`invalid_model`	The selected model or reasoning effort cannot run.	Use a supported configuration or omit the override.
`403`	`repo_access_denied`	The bound user or organization cannot access a requested repo.	Connect or grant repository access.
`429`	`rate_limited`	The key exceeded the applicable general, create, or stream limit.	Wait for `Retry-After`, then retry.
`500`	`internal_error`	Sparkles could not complete the request.	Retry with exponential backoff.
`501`	`file_download_unsupported`	The sandbox daemon predates ACP file reads.	Restart the sandbox on a current image.
`502`	`sandbox_unavailable`	The sandbox coordinator is temporarily unavailable.	Retry with exponential backoff.

JSON responses include Cache-Control: private, no-store. SSE responses use private, no-cache, no-transform so intermediaries neither share nor buffer the stream.

Retry policy

Retry network failures and HTTP 5xx responses with exponential backoff and jitter. For HTTP 429, wait at least the number of seconds in Retry-After. Do not automatically retry validation, authorization, size, media-type, or other conflict errors without changing the request or access configuration. idempotency_in_progress is the exception: retry the identical request and key after a short delay. Creating a sandbox is safe to retry when you preserve its Idempotency-Key. The normalized sandbox request must match the original request for that key.

Example retry decision

export function shouldRetry(status: number) {
	return status === 429 || status >= 500;
}

Cap automated retries, record the final error code, and preserve the original Idempotency-Key across every retry.

Get started

Sparkles CLI

Sandbox API

API reference

Error reference

Retry policy

Example retry decision

​Error reference

​Retry policy

​Example retry decision

Error reference

Retry policy

Example retry decision