API Errors & Retries

Check the HTTP status and code field. Treat error text as an explanation for humans, not a value to match in client logic. Management responses carry an X-Request-Id header; error bodies may also include requestId.

{
  "error": "API key is bound to a different workspace",
  "code": "workspace_mismatch",
  "requestId": "request-id"
}

Common failures

Status	Code	Recovery
`400`	`bad_request`, `invalid_request`	Correct the request body, IDs, query parameters, or schema.
`400`	`workspace_required`, `invalid_workspace`	Supply a valid workspace for an unbound key.
`400` or `403`	`workspace_mismatch`	Align the header/query workspace with the credential's bound workspace.
`401`	`missing_api_key`, `invalid_api_key`	Supply a valid bearer key; log in again if revoked or expired.
`403`	`insufficient_scope`, `forbidden`	Check key scopes, active membership, and owner/admin role for mutations.
`403`	`quota_exceeded`	Check the workspace's active plan and usage limits.
`402`	`insufficient_balance`	Fund the applicable gas balance, then retry after checking execution state.
`404`	`not_found`	Check the deployment, workspace, resource ID, and route.
`409`	`conflict`	Resolve the resource's current state or storage lock before retrying.
`409`	`permissions_not_covered`	Resolve the function's permission requirements against its profile.
`409`	`version_tag_conflict`	Choose another immutable release tag.
`409`	`idempotency_conflict`	Use a new key for a different intended operation.
`409`	`idempotency_in_progress`	Wait for `retryAfterMs`, then retry with the same key and body.
`400`	`invalid_idempotency_key`	Use a non-empty key of at most 128 characters.
`413`	`payload_too_large`	Keep API storage reads and writes within 16 MiB.
`500`	`internal_error`	Save the request ID, check resource state, and contact the deployment operator if it persists.

The upload endpoint also reports archive, checksum, schema, and manifest failures. Rebuild with the current CLI instead of editing the uploaded ZIP by hand.

Permission refusals

An executable binds a function release to concrete args and an execution profile. When the required permissions cannot be covered, binding mutations can fail with 409 permissions_not_covered. Additional message, status, missing, and reasons fields describe the specific failure.

Starting a real run queues work. The execution's later permission check can fail after the HTTP request has succeeded, so inspect the run record and logs too.

Review the manifest, args, and the profile's on-chain role. Extending a role requires its owner. Changing an API key's scopes does not change on-chain permissions.

Function replacement failures

Pause the executable before switching its function. A successful 202 response means the rebuild was accepted, not completed. Poll the executable for pendingFunctionSwitch and lastFunctionSwitchError. If replacement fails, the previous function and sandbox remain available. Resolve the recorded error before requesting a new switch. See release management.

Retry rules

Generate one idempotency key per intended mutation and target resource; retain it across transport retries. Include the resource ID in the key: some action fingerprints use the route template without the target ID. A different resource or change needs a different key.
For a timeout or connection loss, retry the same request with the same key. A replay returns Idempotency-Replayed: true.
For idempotency_in_progress, wait for the response's retryAfterMs.
Fix authentication, validation, permissions, and state errors before trying again. Blind retries will not fix them.
After the 24-hour replay window, inspect the resource before repeating a mutation whose first outcome is unknown.

Idempotency protects management requests; it is not a blanket guarantee that every external effect is exactly once. Uploads deduplicate by immutable tag and archive checksum. Executable webhooks have their own credentials and semantics; see webhooks.