unified-error-protocol

Unified Error Protocol

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

HTTP Status Code Policy

All application-controlled errors return HTTP 200 with status: "error" in the body. This applies to both non-streaming JSON APIs and streaming pre-flight errors.

Only these scenarios use non-200:

• 401 — AUTH_REQUIRED / AUTH_EXPIRED (so transport layer can intercept)
• 403 — ACCESS_DENIED (so transport layer can intercept)
• 404 — Flask routing: no matching route handler
• 413 — WSGI: request body exceeds MAX_CONTENT_LENGTH
• 500 — Unhandled exception that escaped all error handling

Streaming NDJSON APIs:

• Pre-stream validation failure: HTTP 200 + application/json (use stream_preflight_error())
• In-stream error: NDJSON {"type": "error", "error": {...}}
• In-stream warning: NDJSON {"type": "warning", "warning": {...}}

Backend: Non-streaming JSON Format

// Success (HTTP 200)
{"status": "success", "data": {...}}

// Error (HTTP 200 for business errors, 401/403 for auth errors)
{
    "status": "error",
    "error": {
        "code": "TABLE_NOT_FOUND",
        "message": "Table not found",
        "retry": false,
        "detail": "..."  // Only in debug mode
    }
}

Backend: Streaming NDJSON Format

All streaming endpoints use application/x-ndjson. Each line is one JSON object:

{"type": "text_delta", "data": {...}}
{"type": "error", "error": {"code": "LLM_TIMEOUT", "message": "...", "retry": true}}
{"type": "done", "data": {...}}

Backend: How to Handle Errors

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

# Non-streaming: success
return json_ok(data)

# Non-streaming: error (global handler returns HTTP 200, auth errors get 401/403)
raise AppError(ErrorCode.TABLE_NOT_FOUND, "Table not found")

# Streaming: pre-flight error (always HTTP 200)
return stream_preflight_error(AppError(ErrorCode.INVALID_REQUEST, "Bad input"))

# Streaming: in-stream error
yield stream_error_event(classify_and_wrap_llm_error(e))