What can go wrong: failure and error concepts
Development status: Being explored — The design is being explored; its public interface and support are not settled. Some behaviours behind these categories, such as admission control under load, exist in the internal experimental implementation, while job cancellation and refunds are being explored and finality is not connected. There is no released error interface: no error codes, messages, retry rules or limits are published, and nothing is publicly available for live use.
Before you read: Conceptual reference.
What kinds of failures should an application expect, and how would they surface? This page is the single place where failure categories are described. For each category it explains what the category means, how it would surface in general terms, what an application would be expected to do and its status today. It is not an error catalogue.
How to read this page
- Categories, not a catalogue. There are no error codes, messages, retry rules or limits here, because none are published.
- Status per category. Each category carries its own status. Some correspond to behaviour in the internal experimental implementation; others are planned or being explored.
- General practice is labelled. Advice marked “general practice” is ordinary practice for networked systems, not a Cubane-specific rule.
- No borrowed semantics. The behaviour of other platforms, including how they report or reverse failed operations, should not be assumed.
Failures at submission
Refused at submission. Status: Experimental implementation exists — internal prototype only. A submission does not pass a node’s initial checks and is refused. The reasons are not described. In the intended experience, the application would learn that the submission was not accepted. It should not assume success, should tell the user what happened, and should not resubmit unchanged work in the expectation of a different outcome.
Delayed or refused under load. Status: Experimental implementation exists — internal prototype components only; no service is offered. When the network is busy, submissions could be delayed or refused, and the application would receive an indication it can act on. This is a normal condition rather than a fault. What service levels and admission control would mean for an application is described on Service levels and admission control.
Requests can also be affected by protections against abuse and repetition. These are described, with their status, on Request abuse and replay protection; no complete protection against replay is claimed.
Outcomes for confidential jobs
Status of this section: Being explored — the design is being explored; its public interface and support are not settled.
- Still in progress. The result is not yet available. Long-running work is normal for confidential jobs and is not a failure; the application should keep its reference to the job and check progress later.
- Cancelled. The application stopped the work before it completed. A refund could follow, with conditions not described.
- Failed. The job ended without producing a result. Causes are not described; the application should tell its users and decide whether to submit the work again.
The job concepts behind these outcomes are on Confidential jobs: tracking, cancelling and retrieving results.
Results that are not final
Status of this section: Experimental implementation exists — a finality status query exists, but finality is not connected, so nothing is reported as final.
- Today no result is reported as final, because finality is not connected; see Agreement and finality status.
- “Not final” is a condition to design for, not an error. A recorded result can be shown to users, but it should be presented as not yet final.
- How a transaction whose execution does not succeed would be reported is not described. Do not assume that it would be reported or reversed in the way other platforms do.
Conditions outside the application’s control
- Unreachable or slow nodes. General practice: a node may be unreachable or slow to respond, and an application should be designed for that — for example, by reporting the condition honestly rather than treating silence as success.
- Misbehaving participants. Being explored: participants could misbehave. The intended defences are described on Threat model and misbehaviour defences, and none is implemented.
- No security reliance on the prototype. The experimental implementation must not be relied on for security; see Known limitations of the experimental prototype.
Designing for failure
General practice, described conditionally: once Cubane’s interfaces are implemented, enabled and publicly released, applications are expected to follow their versioned error reference. Until then, these ordinary resilience practices apply:
- Treat refusals and delays as normal. Retry later at a reduced rate rather than immediately.
- Make your own operations safe to repeat where duplicates would matter, so that trying again cannot cause the same effect twice in your application.
- Keep references to submitted work and check progress, rather than waiting on it.
- Show users honest states, using the terms on Lifecycle stages used in this documentation.
- Avoid irreversible actions on non-final results. Do not trigger irreversible actions elsewhere on results that are not final.
Assumptions, trust and limitations
Categories may be added, merged or renamed as designs settle; any change would be recorded in the Documentation change log. Categories describe what an application should design for; they do not describe how the network detects or handles any condition internally.
Not yet available, and how this page will grow
Once interfaces are released, versioned error reference with codes and recommended handling would be added and linked from each category. Further technical reference is not yet available.
What this page does not claim
This page does not claim any error codes, messages, retry rules, limits, timings or recovery guarantees; any complete protection against abuse or replay; or that any result is final. Anything not stated here as available should be treated as unavailable.
Related pages
- Service levels and admission control — delays and refusals under load.
- Request abuse and replay protection — protections against excessive or repeated requests.
- Confidential jobs: tracking, cancelling and retrieving results — job outcomes.
- Interfaces and their status — the interfaces through which failures would surface.
Glossary
References
No approved public references yet.
