docs/polaris-broker-api-contract.md (lines 83-91) documents error responses as a flat {"error": ..., "message": ..., "trace_id": ...}. The actual code raises HTTPException(status_code=..., detail={"error": ..., "message": ..., "trace_id": ...}), and FastAPI's default handler wraps detail under a "detail" key with no unwrapping exception handler registered — so real responses are {"detail": {"error": ..., ...}}.
Impact: Need to verify whether any real client (the Spark AuthManager JAR, teehr's ensure_broker_session_token) parses the documented flat shape — if so, this is a live bug (KeyError/None on error paths), not just a doc inaccuracy.
Fix: Either update the doc to match reality, or add an exception handler that unwraps detail to match the documented contract — decide after confirming what consumers actually expect.
docs/polaris-broker-api-contract.md (lines 83-91) documents error responses as a flat {"error": ..., "message": ..., "trace_id": ...}. The actual code raises HTTPException(status_code=..., detail={"error": ..., "message": ..., "trace_id": ...}), and FastAPI's default handler wraps detail under a "detail" key with no unwrapping exception handler registered — so real responses are {"detail": {"error": ..., ...}}.
Impact: Need to verify whether any real client (the Spark AuthManager JAR, teehr's ensure_broker_session_token) parses the documented flat shape — if so, this is a live bug (KeyError/None on error paths), not just a doc inaccuracy.
Fix: Either update the doc to match reality, or add an exception handler that unwraps detail to match the documented contract — decide after confirming what consumers actually expect.