Guides

Error Codes


Every failure an SDK raises carries a code. For orchestration failures the code is the same in every language, which makes it the thing to branch on when the same condition has to be handled in Rust, Python and TypeScript alike — a missing workflow is WORKFLOW_NOT_FOUND in all three, and the conformance suite asserts that on every release.

The class you catch is idiomatic to your language and differs between them.


The two vocabularies

Codes come from two sets, and which one you see tells you what went wrong.

Example codesWhat it means
OrchestrationWORKFLOW_NOT_FOUND, WORKFLOW_ALREADY_EXISTS, TASK_EXECUTION_FAILEDSomething about your workflow or task. The request reached the server and the server had an answer.
TransportTypeScript: UNAVAILABLE, DEADLINE_EXCEEDED. Rust: CONNECTION_FAILED, REQUEST_TIMEOUTSomething about the call itself. The server may never have seen it.

The distinction matters when deciding whether to retry. A transport failure means try again — the server was unreachable and your workflow may be perfectly healthy. WORKFLOW_NOT_FOUND means the server answered, and retrying will produce the same answer.

Transport codes are spelled differently per SDK today, so branch on the orchestration codes for logic you intend to port, and treat transport failures as a category rather than by exact name.


Matching on a code

1
match client.get_workflow_handle("order-123").await {
2
Ok(handle) => { /* ... */ }
3
Err(e) => match e.code() {
4
ErrorCode::WorkflowNotFound => { /* no such workflow */ }
5
ErrorCode::ConnectionFailed => { /* transport — worth retrying */ }
6
_ => return Err(e),
7
},
8
}

Catching by class

Matching on the class is the natural thing to write, and it works — a missing workflow arrives as a workflow error in every SDK, not as a generic failure.

1
use orcher::error::{ClientError, Error};
2
3
match result {
4
Err(Error::Client(ClientError::WorkflowNotFound { workflow_id, .. })) => { /* ... */ }
5
Err(e) => return Err(e),
6
Ok(v) => v,
7
}

OrcherError is the base of everything the TypeScript and Python SDKs raise, so catching it is the way to say "any orcher failure" without listing subclasses.


Why not match on the message

Messages are written for people and get reworded. A check like if "not found" in str(e) passes review, works in testing, and breaks silently the day someone improves the wording — with no compiler or test to catch it.

Codes exist so you never have to do that.