Troubleshooting
Creation is disabled
Section titled “Creation is disabled”503 creation_disabled means no new paid box should be attempted. Do not bypass the endpoint or change networks. Existing authorized reads and deletes may remain available. These docs describe the durable production contract but do not announce public paid-write availability.
The payment challenge is unexpected
Section titled “The payment challenge is unexpected”Do not sign. The durable tuple is x402 v2 exact, Base Mainnet eip155:8453, canonical Base USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, and amount 10000 atomic units. The payee must match the value pinned by the approved client release. An unresolved or unexpected payee is a hard stop.
payment_required means a valid request needs payment. payment_invalid means the presented authorization was rejected. payment_pending means the same request may still be reconciling; reuse its saved authorization and idempotency key rather than signing again. payment_unavailable or facilitator_unavailable is retryable only with the identical paid request.
A send failed after signing
Section titled “A send failed after signing”Preserve the generated ciphertext, idempotency key, and adjacent *.payment.json recovery file. Retry the same command with the same endpoint, input, ciphertext path, price ceiling, and idempotency key. Do not edit the recovery JSON or generate a second authorization while the outcome is ambiguous.
The CLI emits recovery events as JSON lines on stderr. If the idempotency key was generated automatically, recover it from the idempotency_key event.
A capabilities file already exists
Section titled “A capabilities file already exists”Secret-file outputs are create-only and refuse replacement or symlink targets. Choose a new path only for a genuinely new request. For a retry, first determine whether the existing protected file contains the original successful box; do not overwrite it.
Inspect or receive returns 401
Section titled “Inspect or receive returns 401”Confirm that the file contains only the read capability, not the full capability JSON or a write/delete token. Capabilities are scoped and not interchangeable. Do not paste the token into support messages.
The box returns 404 or 410
Section titled “The box returns 404 or 410”404 not_found can mean the box does not exist or is not ready. 410 expired or 410 deleted is terminal for access. There is no renewal or recovery endpoint.
Integrity verification fails
Section titled “Integrity verification fails”Do not decrypt or use the output. Confirm the expected SHA-256 came from a trusted create response or HEAD request and that the box ID, read capability, and endpoint belong to the same handoff. A mismatched upload cannot become readable; a mismatched download is discarded by the repository client.
Rate or capacity limits apply
Section titled “Rate or capacity limits apply”Honor retryable and retry only the identical operation. capacity_reclaiming means bounded cleanup is in progress. capacity_exhausted and rate_limited require backoff; changing IPs or parallelizing retries defeats safety controls and can increase payment ambiguity.
Get support
Section titled “Get support”Send [email protected] the non-secret requestId, UTC timestamp, HTTP status, stable error code, and CLI version or commit. Never send payload bytes, plaintext, recipient identities, payer keys, payment signatures, or capability tokens.