Error codes and how to fix them

Every failed call carries a code. Branch on the code, not on the message or an error class. This page shows where the code appears in each client, which errors to retry, and what every code means.

Read the code in your client

import { SandboxError } from "@tangle-network/sandbox";
 
try {
  await box.exec("npm test");
} catch (error) {
  if (!(error instanceof SandboxError)) throw error;
  if (error.catalogCode === "INVALID_STATE") {
    await box.resume();
  } else {
    console.error(error.code, error.status, error.retryable, error.nextStep, error.requestId);
    throw error;
  }
}

from tangle_sandbox import SandboxError
 
try:
    box.exec("npm test")
except SandboxError as error:
    print(error.code, error.status, error.retryable, error.next_step)
    raise

✗ <what failed> (HTTP 409) — <cause>
  → next: <next step>
  → run: <command>

{
  "ok": false,
  "error": {
    "code": "INVALID_STATE",
    "message": "...",
    "nextStep": "...",
    "retryable": false,
    "fix": { "command": "..." },
    "requestId": "...",
    "status": 409
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request",
    "nextStep": "Fix the field the message names and send the request again.",
    "details": { "issues": [{ "path": "resources.cpuCores", "message": "..." }] }
  }
}

Retry the right errors

Retry only when the code’s Retry column says Yes, and wait for Retry-After when the response has one.

Both SDKs send an Idempotency-Key with every create and reuse it when they send the create again. When no host has room (CAPACITY_EXHAUSTED, HOST_PRESSURE, PLACEMENT_WARMING), they send the same create again for up to 150 seconds, within your request timeout. The second request joins the first, so you never get two sandboxes. In TypeScript, create({ retry: { capacity: false } }) returns CAPACITY_EXHAUSTED at once so you can decide when to try again.

If you send creates yourself, set your own Idempotency-Key header and reuse it for every retry of the same create:

curl -s https://sandbox.tangle.tools/v1/sandboxes \
  -H "Authorization: Bearer $TANGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: build-4821" \
  -d '{"name":"build-4821"}'

Errors you will see most

• CAPACITY_EXHAUSTED, HOST_PRESSURE (503) on create. No host has room right now. The SDKs retry for you; see Retry the right errors.
• QUOTA_EXCEEDED, CONCURRENT_LIMIT (429) on create. You reached your plan’s limit of running sandboxes. Stop or delete one, or raise your plan. See Limits and timeouts.
• RESOURCES_EXCEED_LIMIT (400) on create. The CPU, memory or disk you named is above your account’s ceiling. The response names the field, the requested and the allowed value. Read your ceiling with client.shapes().
• COMPLIANCE_NOT_ENTITLED (403). The create asked for compliance: { hipaa: true } and the key has no HIPAA entitlement.
• COMPLIANCE_CAPACITY_UNAVAILABLE, COMPLIANCE_CELL_UNAVAILABLE (503). No HIPAA capacity can take the sandbox now, and it is never placed anywhere else. Retry the first after Retry-After; retry the second later, and contact support if it persists.
• CHILDREN_EXIST (409) on delete. The sandbox has live branches. Delete them first, or delete the whole family with DELETE /v1/sandboxes/{id}?cascade=true or client.deleteMatching(filter, { cascade: true }).
• IMAGE_BUILDS_DISABLED (403) on POST /v1/images. The hosted service does not build images. Start from an environment or a pushed image reference; see Templates and images.
• GPU_PROVIDER_NOT_CONFIGURED (503). No GPU provider is set up for the service you called. Create the sandbox without a GPU.
• PROFILE_INVALID (CLI exit 65). tangle agent profile validate or a command that loads an AgentProfile found it invalid. The message names the field.

Every catalog code

The SDKs, the CLI and the API share this catalog. What to do matches the nextStep your client receives. Retry says whether repeating the same request can succeed.

Other codes the API sends

These codes come from specific routes. The SDKs map each to the nearest catalog code in catalogCode.

CLI exit codes

Next steps

• Troubleshooting: fixes for problems that are not a single error code.
• Limits and timeouts: the sizes, rates and timeouts behind 413 and 429 answers.
• REST API: the error body and headers on every route.