Error Handling

Akan errors are built around one simple rule: server code throws a typed dictionary key, and the client shows the translated message for that key.

Declare user-facing errors in the module dictionary.
Throw `Err` from document or service code when a business rule fails.
Let fetch restore the response as an `Err`, then show it with `msg.error()`.

Declare Errors

Start in the dictionary. The keys you declare here become the only valid keys for `Err`, so typo mistakes are caught by TypeScript.

order.dictionary.ts

Throw Err

Use `Err` for business rules that users can understand and fix. A document method is a good place for state rules because every service shares the same rule.

order.document.ts

Choose Status

`new Err()` uses 400 by default. When the HTTP meaning matters, pick a named helper. This keeps API responses clear without making every rule verbose.

`Err.NotFound`: a requested record does not exist.
`Err.Conflict`: the current state cannot accept this action.
`Err.Forbidden`: the user is known but may not do this action.

order.service.ts

Use Data

Pass `data` when the translated message needs values. The server keeps the dictionary key as `error`, and sends `data` beside it for interpolation.

order.document.ts

Client Handling

Akan fetch restores an error response as `Err`. In UI code, catch it and pass its key and data to `msg.error()`.

Order.Util.tsx

Response Shape

HTTP and websocket errors use the same simple shape. Most app code does not need to build this by hand, but knowing it makes debugging easier.

Error response

Tips

Use `Err` for user-facing domain failures. Use normal `Error` for programmer mistakes, missing setup, or impossible states.
Put repeated state rules in document methods. Put cross-model checks and loading logic in services.
Name keys by domain and reason: `order.error.notDraft`, `order.error.stockNotEnough`, `user.error.wrongPassword`.
Do not translate on the server. Send the key and data, then let the client choose the user's language.

Error Handling

Akan errors are built around one simple rule: server code throws a typed dictionary key, and the client shows the translated message for that key.

Declare user-facing errors in the module dictionary.
Throw `Err` from document or service code when a business rule fails.
Let fetch restore the response as an `Err`, then show it with `msg.error()`.

Declare Errors

Start in the dictionary. The keys you declare here become the only valid keys for `Err`, so typo mistakes are caught by TypeScript.

order.dictionary.ts

Throw Err

Use `Err` for business rules that users can understand and fix. A document method is a good place for state rules because every service shares the same rule.

order.document.ts

Choose Status

`new Err()` uses 400 by default. When the HTTP meaning matters, pick a named helper. This keeps API responses clear without making every rule verbose.

`Err.NotFound`: a requested record does not exist.
`Err.Conflict`: the current state cannot accept this action.
`Err.Forbidden`: the user is known but may not do this action.

order.service.ts

Use Data

Pass `data` when the translated message needs values. The server keeps the dictionary key as `error`, and sends `data` beside it for interpolation.

order.document.ts

Client Handling

Akan fetch restores an error response as `Err`. In UI code, catch it and pass its key and data to `msg.error()`.

Order.Util.tsx

Response Shape

HTTP and websocket errors use the same simple shape. Most app code does not need to build this by hand, but knowing it makes debugging easier.

Error response

Tips

Use `Err` for user-facing domain failures. Use normal `Error` for programmer mistakes, missing setup, or impossible states.
Put repeated state rules in document methods. Put cross-model checks and loading logic in services.
Name keys by domain and reason: `order.error.notDraft`, `order.error.stockNotEnough`, `user.error.wrongPassword`.
Do not translate on the server. Send the key and data, then let the client choose the user's language.