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 codes | What it means | |
|---|---|---|
| Orchestration | WORKFLOW_NOT_FOUND, WORKFLOW_ALREADY_EXISTS, TASK_EXECUTION_FAILED | Something about your workflow or task. The request reached the server and the server had an answer. |
| Transport | TypeScript: UNAVAILABLE, DEADLINE_EXCEEDED. Rust: CONNECTION_FAILED, REQUEST_TIMEOUT | Something 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
1match 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}Python spells its codes as an enum whose members carry the name — compare
e.code.name, or the member itself. TypeScript exposes two enums because it
carries both vocabularies: ExecutionErrorCode for orchestration codes and
ErrorCode for transport ones.
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.
1use orcher::error::{ClientError, Error};23match 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.