Errors

All non-/health responses use the same ErrBody { error } shape on failure. The HTTP status code maps to the failure category.

Status	Meaning
400	malformed JSON / missing required argument
401	bad / missing token
403	endpoint requires elevated auth (e.g. encrypted dispatch)
404	unknown command / route
429	PIN bucket locked (too many wrong PINs)
500	dispatcher panicked or returned Err(...)

Response shape

{ "error": "wrong pin" }

Always JSON, even on 4xx — clients can consistently if (!resp.ok) { const { error } = await resp.json(); ... }.

Distinguishing 404 cases

There are two flavors of 404:

• Unknown route — you hit a path that doesn't exist. Returned as plain HTML by axum's default fallback.
• Unknown command — you POST /invoke with a cmd the dispatcher doesn't recognize. Returned as {"error":"unknown command: <name>"}.

If you're unsure whether a feature is exposed, check the dispatcher source (api_dispatch.rs) before opening an issue.

Dispatcher errors

Most 500 responses come from a Tauri command that returned Err(...) (network failure, file-system race, lua compile error). The error text is forwarded verbatim — no scrubbing — so the message you see is the exact one the bot logged.

If 500 keeps repeating without an obvious cause, tail the events stream — the same error usually shows up there with full context (which bot, which packet, which scope).