error-response-safety

Error Response Safety

Never return raw exception text (str(e), f"...{e}") directly in HTTP responses. Python exceptions may contain stack traces, file paths, database connection strings, API keys, or internal IP addresses — all of which are security risks (CWE-209).

See docs/dev-guides/7-unified-error-handling.md for the full error handling contract.

Unified Error System

New error paths should use the AppError / error_handler infrastructure from errors.py and error_handler.py. Legacy message / error_message bodies are historical formats; do not add compatibility branches for them in new code. All application-controlled errors return HTTP 200 with status: "error" in the body. Only auth errors (401/403) and uncontrolled transport errors (404/413/500) use non-200.

Non-streaming routes

Raise AppError for new code or when structured error codes are useful. The global error handler returns HTTP 200 + JSON error envelope:

from data_formulator.errors import AppError, ErrorCode

# Business error — raise with appropriate code and safe message
raise AppError(ErrorCode.TABLE_NOT_FOUND, "Table not found")

# LLM / external API error — use classify_and_wrap_llm_error
from data_formulator.error_handler import classify_and_wrap_llm_error

except Exception as e:
    raise classify_and_wrap_llm_error(e) from e

Streaming routes

Use stream_error_event() to yield a unified NDJSON error line. Validation before the stream starts returns 200 application/json (not NDJSON):

from data_formulator.errors import AppError, ErrorCode
from data_formulator.error_handler import (
    classify_and_wrap_llm_error,
    stream_error_event,
    stream_preflight_error,
)

except AppError as e:
    yield stream_error_event(e)
except Exception as e:
    yield stream_error_event(classify_and_wrap_llm_error(e))

Real examples from migrated endpoints

# /data-agent-streaming — standard NDJSON error event
except Exception as e:
    logger.error("Error in data-agent-streaming", exc_info=e)
    from data_formulator.error_handler import stream_error_event, classify_and_wrap_llm_error
    yield stream_error_event(classify_and_wrap_llm_error(e))

# /generate-report-chat — same pattern
except Exception as e:
    logger.exception("generate-report-chat failed")
    from data_formulator.error_handler import stream_error_event, classify_and_wrap_llm_error
    yield stream_error_event(classify_and_wrap_llm_error(e))

# Validation failure before stream starts — use 200 JSON, not NDJSON
if not request.is_json:
    return stream_preflight_error(AppError(ErrorCode.INVALID_REQUEST, "Invalid request"))