---
title: "Start with the boundary that failed."
description: "Diagnose Wildflower Computer authentication, provider profiles, sandbox IDs, file encodings, rate limits, uncertain creates, and documentation drift."
canonical: "https://wildflower.computer/docs/troubleshooting/"
openapi_version: "0.8.0"
source_revision: "788b7325a454b8b753a7d614247d5694bad5c967"
---

# 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.

```bash
curl --fail-with-body "$WILDFLOWER_URL/v1/sandboxes" \
  -H "Authorization: Bearer $WILDFLOWER_API_KEY" \
  --dump-header /tmp/wildflower-headers.txt

rg -i 'x-request-id|retry-after|server-timing' \
  /tmp/wildflower-headers.txt
```

## Common symptoms

### missing_api_key

Confirm the `Authorization: Bearer …` header reaches the API. This is the Wildflower project key, not the provider key.

### provider_profile_not_found

Connect the provider for this project or supply a typed inline provider credential and all required connection context.

### authentication_error

The provider rejected its credential. Rotate or reconnect that provider profile; do not replace the Wildflower bearer key.

### invalid_sandbox_id / sandbox_not_found

Use the opaque ID returned by create. IDs are project-scoped; a missing ID and another project's ID intentionally fail alike.

### invalid_file_content / file_not_utf8

Make `encoding` match the supplied content. Use`base64` for arbitrary bytes.

### rate_limited

Honor `Retry-After`, add jitter, and reduce request or concurrency bursts.

### Uncertain create outcome

Do not invent a new idempotency key. Retain the operation ID and inspect the project registry before operator reconciliation.

### Documentation source rejected

Use a clean API checkout at exact `origin/main`, run`sdk:check`, then repeat the local website refresh.

> **A command exit code is not an API error**
>
> A command that exits non-zero still returns a successful command result. Read `exitCode`, `stdout`, and`stderr` before treating the request as a transport failure.

## 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 the [generated API reference](https://wildflower.computer/docs/reference/) and include the response's`X-Request-Id` in the investigation.