gpt-5.3 codex review: Phase 4

tests/api/test_error_responses.py

@@ -33,13 +33,13 @@ class TestApiErrorResponses:
         assert response.status_code == 400
         payload = response.json()
         assert payload["error_id"] == "abc12345"
-        assert payload["category"] == "validation_error"
+        assert payload["category"] == "validation"
         assert payload["message"] == "Bad upload payload"
         assert payload["suggestion"] == "Upload a non-empty file"
         assert "timestamp" in payload
 
-    def test_unexpected_error_returns_internal_unexpected_envelope(self):
-        """Unexpected exceptions map to internal_unexpected_error with 500."""
+    def test_unexpected_error_returns_internal_envelope(self):
+        """Unexpected exceptions map to canonical internal category with 500."""
         app = FastAPI()
         register_error_handlers(app)
 
@@ -52,6 +52,42 @@ class TestApiErrorResponses:
 
         assert response.status_code == 500
         payload = response.json()
-        assert payload["category"] == "internal_unexpected_error"
+        assert payload["category"] == "internal"
         assert "error_id" in payload
         assert payload["suggestion"]
+
+    @pytest.mark.parametrize(
+        ("category", "expected_status", "expected_envelope_category"),
+        [
+            (ErrorCategory.USER_INPUT, 400, "validation"),
+            (ErrorCategory.NOT_FOUND, 404, "not_found"),
+            (ErrorCategory.CONFLICT, 409, "conflict"),
+            (ErrorCategory.EXTERNAL_PROVIDER, 503, "external"),
+            (ErrorCategory.INFRA_TRANSIENT, 503, "timeout"),
+            (ErrorCategory.INFRA_PERSISTENT, 500, "internal"),
+            (ErrorCategory.INTERNAL_UNEXPECTED, 500, "internal"),
+        ],
+    )
+    def test_app_error_category_mapping_uses_canonical_envelope_taxonomy(
+        self,
+        category: ErrorCategory,
+        expected_status: int,
+        expected_envelope_category: str,
+    ):
+        app = FastAPI()
+        register_error_handlers(app)
+
+        @app.get("/category")
+        def category_route() -> dict[str, str]:
+            raise AppError(
+                "Category test",
+                category=category,
+                suggestion="retry",
+                error_id="cat12345",
+            )
+
+        client = TestClient(app)
+        response = client.get("/category")
+
+        assert response.status_code == expected_status
+        assert response.json()["category"] == expected_envelope_category

tests/api/test_v4_documents.py

@@ -224,4 +224,4 @@ def test_duplicate_document_person_link_returns_conflict_envelope(tmp_path):
 
     assert second.status_code == 409
     payload = second.json()
-    assert payload["category"] == "conflict_error"
+    assert payload["category"] == "conflict"