# HTTP return values and exception propagation

This page describes the **source implementation**, not a guarantee established by a live MG400 test.

## Automatic dispatch

The default server registers `DobotCtrl` with `api_spec=None`. `DeviceRouter._dispatch_handler()` receives `method`, `args`, and `kwargs`, decodes arguments using `adapter.unpack_args()` / `adapter.unpack_kwargs()`, and calls the corresponding public member. Coroutine functions are awaited; synchronous functions are invoked directly in the async handler. The result is serialized by `adapter.pack_result()` into a JSON response.

An explicit `HTTPException` is propagated. Other exceptions are logged and converted into HTTP 500 with `detail=str(e)`. The conversion does **not** preserve the original Python exception type on the client. An HTTP 200 response establishes successful dispatch/serialization only; it does not establish successful robot motion or a verified physical I/O state.

## Clients

`SyncDeviceClient.dispatch()` and `AsyncDeviceClient.dispatch()` send POST requests to `/instance/dobot/__dispatch__` and deserialize the result using `adapter.unpack_result()`. In automatic mode they fetch `__meta__` to obtain return-type descriptors; this does not prove that an unannotated return value has the expected application type.

Both `_post()` implementations call `raise_for_status()`. An HTTP 4xx/5xx therefore raises `httpx.HTTPStatusError` rather than reconstructing the server-side Python exception. Network errors and HTTP timeouts are not robot-side motion timeouts. The configured HTTP timeout must not be interpreted as a stop or cancellation of motion already accepted by the controller.

## Operational implications

- Distinguish transport failure, HTTP dispatch failure, command acknowledgement, and physical completion.
- On a timeout, **do not automatically retry a movement command** without reconciling robot state; the previous request may have been accepted.
- Feedback freshness and alarm reporting limitations documented elsewhere remain applicable through HTTP.
- This review is based on static source inspection. It does not include an HTTP integration test or an MG400 test.

See [motion dispatch](motion_dispatch_audit.md), [feedback/error review](error_feedback_audit.md), and [I/O and state](io_state_error_audit.md).