Guides / diagnosis

Start with the boundary that failed.

Wildflower separates API authentication, provider access, project registry state, and provider execution. Preserve the stable error code and request ID before changing anything; together they narrow the failure quickly.

Capture one useful failure

Keep the JSON error body plus correlation and timing headers. Never include the Wildflower bearer key, provider credential, command output, or file content in a support report.

1curl --fail-with-body "$WILDFLOWER_URL/v1/sandboxes" \2  -H "Authorization: Bearer $WILDFLOWER_API_KEY" \3  --dump-header /tmp/wildflower-headers.txt45rg -i 'x-request-id|retry-after|server-timing' \6  /tmp/wildflower-headers.txt

Common symptoms

Generated error vocabulary

These codes come from the same generated contract as the SDKs and reference pages:

• invalid_request

  The request did not satisfy the endpoint contract.

  Not retryable. Correct the fields identified by the response message before sending the request again.

• payload_too_large

  The request body or file content exceeded the supported size limit.

  Not retryable. Reduce the payload to the documented limit or split the work into smaller operations.

• request_timeout

  Wildflower stopped waiting before the operation completed.

  Retryable. Retry with exponential backoff. For create operations, first reconcile using the operation ID because the provider may have succeeded.

• invalid_idempotency_key

  The Idempotency-Key header was missing, malformed, or outside the supported length.

  Not retryable. Send a stable, non-secret key that follows the documented Idempotency-Key constraints.

• idempotency_conflict

  The same idempotency key was reused with a different create request.

  Not retryable. Reuse the key only for the identical logical request, or generate a new key for changed input.

• idempotency_in_progress

  An identical idempotent operation is still running.

  Retryable. Wait for the Retry-After interval and retry the same request with the same idempotency key.

• idempotency_outcome_unknown

  Wildflower cannot safely determine whether a prior create reached the provider.

  Not retryable. Do not issue a blind create retry. Reconcile the operation ID with the sandbox registry or support.

• idempotency_unavailable

  The idempotency store was temporarily unavailable.

  Retryable. Retry with exponential backoff and the same idempotency key.

• sandbox_registry_unavailable

  The sandbox registry could not be read or updated.

  Retryable. Retry with exponential backoff. For create or delete, preserve identifiers and reconcile state before repeating the operation.

• sandbox_create_outcome_unknown

  The provider create outcome could not be confirmed.

  Not retryable. Do not create again automatically. Use the operation ID to reconcile the provider and Wildflower registry.

• invalid_file_content

  File content was not valid for the declared wire encoding.

  Not retryable. Encode the content as valid UTF-8 or base64 and make the encoding field match.

• file_not_utf8

  The requested file contains bytes that cannot be returned as UTF-8.

  Not retryable. Read the file with base64 encoding instead.

• file_operation_failed

  The provider could not complete the requested file operation.

  Not retryable. Verify that the path exists, is permitted, and is within provider limits before retrying.

• missing_api_key

  No usable Wildflower or provider credential was supplied.

  Not retryable. Configure the required project API key and connect or supply the provider credential.

• provider_profiles_unavailable

  Connected provider profiles could not be loaded.

  Retryable. Retry with exponential backoff; do not replace a stored profile unless the failure persists.

• provider_profile_not_found

  The project has no connected profile for the requested provider.

  Not retryable. Connect that provider or supply a valid inline provider credential for the request.

• provider_operation_unavailable

  A prior deep verification proved that the connected provider credential cannot perform the requested operation.

  Not retryable. Use the response operation, reason, and remediation fields to grant the missing permission, replace the credential, or choose a supported provider.

• invalid_sandbox_id

  The sandbox ID is malformed or names a provider that does not match the route.

  Not retryable. Use the opaque sandbox ID returned by Wildflower without modifying it.

• provider_invalid_request

  The selected provider rejected the normalized request as invalid.

  Not retryable. Correct provider-specific image, timeout, command, or connection settings before retrying.

• authentication_error

  A Wildflower or upstream provider credential was rejected.

  Not retryable. Replace or reconnect the invalid credential, then retry the original operation.

• control_plane_conflict

  The requested account or project mutation conflicts with current control-plane state.

  Not retryable. Refresh the current resource state and submit a mutation that satisfies its ownership and lifecycle rules.

• last_account_owner

  The operation would leave an organization without an owner.

  Not retryable. Promote another member to owner before removing, demoting, or transferring the current owner.

• personal_account_immutable

  The requested ownership or membership change is not allowed for a personal account.

  Not retryable. Use an organization account for shared ownership and membership changes.

• account_deleting

  The account is already in its deletion lifecycle.

  Not retryable. Wait for deletion to finish and avoid starting new work in the account.

• sandbox_not_found

  No sandbox visible to this project matches the supplied ID.

  Not retryable. Check the project and sandbox ID; a previously deleted sandbox cannot be restored through this endpoint.

• rate_limited

  The request exceeded a Wildflower or provider rate limit.

  Retryable. Wait for Retry-After when present, then retry with exponential backoff and jitter.

• provider_unavailable

  The selected provider or customer-owned bridge is temporarily unavailable.

  Retryable. Retry with exponential backoff or select another provider when workload portability permits.

• provider_error

  The provider returned a failure that Wildflower could not classify more narrowly.

  Not retryable. Inspect the safe response message and operation ID; retry only when the provider condition is known to be transient.

• internal_error

  Wildflower encountered an unexpected server-side failure.

  Retryable. Retry with exponential backoff and retain the request or operation ID for support if the failure repeats.

• legal_acceptance_required

  The actor or account must accept the current legal release before continuing.

  Not retryable. Review and accept the required documents, then repeat the blocked operation.

• legal_release_changed

  The legal release changed between review and acceptance.

  Not retryable. Fetch and review the new current release before submitting acceptance again.

• legal_not_found

  The requested legal document or release does not exist.

  Not retryable. Refresh the legal manifest and use a published document and version.

• legal_unavailable

  The legal publication or acceptance store is temporarily unavailable.

  Retryable. Retry with exponential backoff; do not assume acceptance was recorded unless it can be confirmed.

• invalid_email_webhook

  The inbound email webhook signature or payload was invalid.

  Not retryable. Verify webhook signing configuration and send a payload that matches the documented provider event shape.

When a code is unfamiliar, use thegenerated API reference and include the response'sX-Request-Id in the investigation.