Retries & Entity Status

Vault creation, stream creation, attachments, signatures and asset operations all settle asynchronously on-chain. When one of them fails, these two endpoints are how you find out why and re-drive it.

This is the answer to "my vault is stuck".

Checking what happened

GET /status/{entity_type}/{entity_id}

Returns considerably more than a status string:

Field	Meaning
retry_count / max_retries	How many attempts have been made, and the ceiling — 3 by default for both vaults and assets
last_error, last_error_at	The most recent failure and when
last_retry_at	When it was last re-driven
final_failure	true means stop — it will not be retried again
status_before_error	The lifecycle stage it failed at
credit_refunded	Whether the credit was returned

Re-driving

POST /retry     {"entity_type": "...", "entity_id": "...", "force": false}

A refusal comes back as 200 with success: false and a reason — not a 4xx. Check the body, not just the status code.

entity_type accepts exactly two values: vault and asset.

warning

stream, data_attachment and signature are not re-drivable, even though stream.failed, data_attachment.failed and signature.failed appear as webhook event names. POST /retry answers with 200 and {"success": false, "reason": "Unsupported entity type: ..."}, and the status route returns 404 on the vault path or 400 on the asset path. A failed stream or attachment has to be re-created, not retried.

warning

force: true does different things per resource:

• vault — raises the retry ceiling from 3 to 100. It still refuses if no status_before_error was recorded.
• asset — bypasses three guards at once: the retry ceiling, the final_failure flag, and the requirement that the asset be in ERROR state. Forcing a healthy asset re-drives it.

Use it only after reading last_error and fixing the underlying cause — forcing a retry on an operation that partially succeeded on-chain can produce duplicate transactions.

Pair it with webhooks

Rather than polling, subscribe to vault.failed, stream.failed, data_attachment.failed, signature.failed and asset.error — see Webhooks — and call GET /status/{entity_type}/{entity_id} when one arrives.