LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows
Python ai-agentsdata-engineeringdocument-aigenerative-aiidpjson-extractionllmmcp-serverocrpdf-extractionprompt-engineeringstructured-output
UN-1412 [FIX] Mirror API deployment execute errors into message.error (#2334)
Deepak K9b3efba75839
diff --git a/backend/api_v2/api_deployment_views.py b/backend/api_v2/api_deployment_views.pyindex 891ed1c57..7b85f1e64 100644--- a/backend/api_v2/api_deployment_views.py+++ b/backend/api_v2/api_deployment_views.py@@ -32,6 +32,7 @@ from api_v2.api_deployment_dto_registry import ApiDeploymentDTORegistryfrom api_v2.constants import ApiExecutionfrom api_v2.deployment_helper import DeploymentHelperfrom api_v2.dto import DeploymentExecutionDTO+from api_v2.error_message import add_error_messagefrom api_v2.exceptions import (NoActiveAPIKeyError,RateLimitExceeded,@@ -41,6 +42,7 @@ from api_v2.models import APIDeploymentfrom api_v2.openapi_schema import (API_DEPLOYMENT_LIST_SCHEMA,DEPLOYMENT_EXECUTION_SCHEMA,+ DeploymentAutoSchema,)from api_v2.rate_limiter import APIDeploymentRateLimiterfrom api_v2.serializers import (@@ -61,6 +63,8 @@ logger = logging.getLogger(__name__)@DEPLOYMENT_EXECUTION_SCHEMAclass DeploymentExecution(views.APIView):+ schema = DeploymentAutoSchema()+def initialize_request(self, request: Request, *args: Any, **kwargs: Any) -> Request:"""To remove csrf request for public API.@@ -73,6 +77,14 @@ class DeploymentExecution(views.APIView):request.csrf_processing_done = Truereturn super().initialize_request(request, *args, **kwargs)+ def handle_exception(self, exc: Exception) -> Response:+ response = super().handle_exception(exc)+ # On the status read `message` is the result payload, and published+ # clients copy it out as the extraction result without checking.+ if self.request.method == "POST":+ add_error_message(response.data)+ return response+@DeploymentHelper.validate_api_keydef post(self,diff --git a/backend/api_v2/error_message.py b/backend/api_v2/error_message.pynew file mode 100644index 000000000..61ca93f8d--- /dev/null+++ b/backend/api_v2/error_message.py@@ -0,0 +1,37 @@+from typing import Any++from workflow_manager.workflow_v2.enums import ExecutionStatus++MESSAGE_KEY = "message"+++def flatten_error(data: dict[str, Any]) -> str:+ """Join the details without their `attr`, as the published Python client+ already renders a refused request, so the text callers see is unchanged.+ """+ errors = data.get("errors")+ if isinstance(errors, list):+ return "; ".join(+ str(err["detail"])+ for err in errors+ if isinstance(err, dict) and err.get("detail")+ )+ if errors is not None:+ return str(errors)+ return str(data.get("error", ""))+++def add_error_message(data: Any) -> Any:+ """Mirror an error body into the `message.error` slot the execute response+ uses, so a client reads one key for every outcome.++ Strictly additive: published clients parse the existing keys, so they are+ left exactly as the exception handler produced them.+ """+ if not isinstance(data, dict) or MESSAGE_KEY in data:+ return data+ data[MESSAGE_KEY] = {+ "execution_status": ExecutionStatus.ERROR.value,+ "error": flatten_error(data),+ }+ return datadiff --git a/backend/api_v2/openapi_schema.py b/backend/api_v2/openapi_schema.pyindex 34e63ce2b..a82e92739 100644--- a/backend/api_v2/openapi_schema.py+++ b/backend/api_v2/openapi_schema.py@@ -9,15 +9,18 @@ they are written for the caller rather than the maintainer."""from drf_spectacular.utils import (+ OpenApiExample,OpenApiParameter,OpenApiResponse,extend_schema,extend_schema_serializer,extend_schema_view,)+from drf_standardized_errors.openapi import AutoSchema as StandardizedErrorsAutoSchemafrom platform_api.openapi_schema import PlatformKeyErrorfrom rest_framework import serializers+from api_v2.error_message import add_error_messagefrom api_v2.models import API_NAME_MAX_LENGTH, DESCRIPTION_MAX_LENGTHfrom api_v2.serializers import (APIDeploymentListSerializer,@@ -116,6 +119,44 @@ class ErrorResponse(serializers.Serializer):errors = ErrorDetail(many=True)+class ErrorMessage(serializers.Serializer):+ """The failure in the same place an execution reports its own."""++ execution_status = serializers.CharField(help_text="Always `ERROR`.")+ error = serializers.CharField(+ help_text="Every problem in `errors`, as one readable string."+ )+++class DeploymentErrorResponse(ErrorResponse):+ """The body of a rejected execute request.++ Carries `message.error` as well, so a client can read the failure from the+ key an execution reports it in, whatever went wrong.+ """++ message = ErrorMessage()+++class DeploymentAutoSchema(StandardizedErrorsAutoSchema):+ """Shows the injected handler examples on execute with the `message` block+ the deployment view adds, so they match `DeploymentErrorResponse`.+ """++ def _get_error_response_examples(self) -> list[OpenApiExample]:+ if self.method != "POST":+ return super()._get_error_response_examples()+ return [+ OpenApiExample(+ example.name,+ value=add_error_message(dict(example.value)),+ response_only=example.response_only,+ status_codes=example.status_codes,+ )+ for example in super()._get_error_response_examples()+ ]++# Restates the route's own pattern so a client rejects a mistyped identifier# without a round trip.PATH_SEGMENT = {"type": "string", "pattern": r"^[\w-]+$"}@@ -156,20 +197,29 @@ DEPLOYMENT_ERRORS = {),}+# The execute endpoint also mirrors each rejection into `message`; the status+# read does not, because there `message` is the result.+EXECUTE_REQUEST_ERRORS = {+ code: OpenApiResponse(DeploymentErrorResponse, description=response.description)+ for code, response in DEPLOYMENT_ERRORS.items()+}+# Only the execution endpoint fetches documents and takes a rate-limit slot, so# these cannot arise on the status read.EXECUTE_ERRORS = {413: OpenApiResponse(- ErrorResponse, description="A referenced document is larger than the limit."+ DeploymentErrorResponse,+ description="A referenced document is larger than the limit.",),429: OpenApiResponse(- ErrorResponse, description="Too many concurrent executions; retry later."+ DeploymentErrorResponse,+ description="Too many concurrent executions; retry later.",),502: OpenApiResponse(- ErrorResponse, description="A referenced document could not be fetched."+ DeploymentErrorResponse, description="A referenced document could not be fetched."),504: OpenApiResponse(- ErrorResponse, description="Fetching a referenced document timed out."+ DeploymentErrorResponse, description="Fetching a referenced document timed out."),}@@ -220,7 +270,7 @@ DEPLOYMENT_EXECUTION_SCHEMA = extend_schema_view(description="The deployment could not be run; the body carries the ""execution that failed.",),- **DEPLOYMENT_ERRORS,+ **EXECUTE_REQUEST_ERRORS,**EXECUTE_ERRORS,},description=EXECUTE_DESCRIPTION,diff --git a/backend/api_v2/tests/test_deployment_auth.py b/backend/api_v2/tests/test_deployment_auth.pyindex ccbf307fa..f3d0584b2 100644--- a/backend/api_v2/tests/test_deployment_auth.py+++ b/backend/api_v2/tests/test_deployment_auth.py@@ -90,6 +90,11 @@ class APIDeploymentAuthTest(TestCase):with self.subTest(label):response = self._post(api_name, auth, org)assert response.status_code == expected, response.data+ assert response.data["type"] == "client_error", response.data+ assert response.data["message"] == {+ "execution_status": "ERROR",+ "error": response.data["errors"][0]["detail"],+ }execute_workflow.assert_not_called()diff --git a/backend/api_v2/tests/test_deployment_error_message.py b/backend/api_v2/tests/test_deployment_error_message.pynew file mode 100644index 000000000..d0d4da639--- /dev/null+++ b/backend/api_v2/tests/test_deployment_error_message.py@@ -0,0 +1,138 @@+"""Every error the execute endpoint returns also carries `message.error`, and+the keys clients already parse are left untouched on both endpoints.+"""++from __future__ import annotations++from unittest.mock import patch++import pytest+from middleware.exception import drf_logging_exc_handler+from rest_framework.exceptions import ValidationError+from rest_framework.test import APIRequestFactory++from api_v2.api_deployment_views import DeploymentExecution+from api_v2.error_message import add_error_message, flatten_error+from api_v2.exceptions import (+ APINotFound,+ InvalidAPIRequest,+ RateLimitExceeded,+ UnauthorizedKey,+)+from api_v2.tests.test_docstudio_spec import _schema++URL = "/deployment/api/org/api/"+AUTH = {"HTTP_AUTHORIZATION": "Bearer 00000000-0000-0000-0000-000000000000"}++RAISED = [+ (UnauthorizedKey(), 401, "Unauthorized"),+ (APINotFound(), 404, "API not found"),+ (InvalidAPIRequest("Missing params api_name"), 400, "Missing params api_name"),+ (RateLimitExceeded(detail="Too many"), 429, "Too many"),+ (+ ValidationError({"timeout": ["Ensure this value is less than 300."]}),+ 400,+ "Ensure this value is less than 300.",+ ),+]+++def _call(method: str, **headers):+ request = getattr(APIRequestFactory(), method)(URL, **headers)+ return DeploymentExecution.as_view()(request, org_name="org", api_name="api")+++def _raise(method: str, exc: Exception):+ with patch(+ "api_v2.api_deployment_views.DeploymentHelper.validate_parameters",+ side_effect=exc,+ ):+ return _call(method, **AUTH)+++def _handler_body(exc: Exception, method: str) -> dict:+ """What the project-wide handler sends for `exc` on its own, i.e. the body+ clients parsed before `message` was added.+ """+ request = getattr(APIRequestFactory(), method)(URL)+ return dict(drf_logging_exc_handler(exc=exc, context={"request": request}).data)+++def test_missing_key_on_execute_keeps_its_body_and_gains_message() -> None:+ response = _call("post")++ assert response.status_code == 403+ legacy = {k: v for k, v in response.data.items() if k != "message"}+ assert legacy == {+ "type": "client_error",+ "errors": [{"code": "error", "detail": "Missing api key", "attr": None}],+ }+ assert response.data["message"] == {+ "execution_status": "ERROR",+ "error": "Missing api key",+ }++[email protected](("exc", "status", "error"), RAISED)+def test_execute_errors_keep_the_handler_body_and_gain_message(+ exc, status, error+) -> None:+ response = _raise("post", exc)++ assert response.status_code == status+ legacy = {k: v for k, v in response.data.items() if k != "message"}+ assert legacy == _handler_body(exc, "post")+ assert response.data["message"] == {"execution_status": "ERROR", "error": error}++[email protected](("exc", "status", "error"), RAISED)+def test_status_read_errors_are_unchanged(exc, status, error) -> None:+ """On the status read `message` is the result, and the published client+ copies it out as one; an error block there would read as a result.+ """+ response = _raise("get", exc)++ assert response.status_code == status+ assert dict(response.data) == _handler_body(exc, "get")+++def test_the_documented_execute_error_body_is_the_one_the_view_sends() -> None:+ response = _raise("post", UnauthorizedKey())++ assert set(response.data) == set(_schema("DeploymentErrorResponse")["required"])+ assert set(response.data["message"]) == set(_schema("ErrorMessage")["required"])+++def test_details_are_joined_without_their_field() -> None:+ """Matches the published client's own rendering of a refused request, so+ the error text a caller sees does not change.+ """+ data = {+ "type": "validation_error",+ "errors": [+ {"code": "invalid", "detail": "Not a valid URL.", "attr": "presigned_urls"},+ {"code": "invalid", "detail": "At least one file.", "attr": None},+ ],+ }++ assert flatten_error(data) == "Not a valid URL.; At least one file."+++ ("data", "error"),+ [+ # The cloud subscription middleware sends `errors` as a plain string.+ ({"type": "subscription_error", "errors": "Trial expired"}, "Trial expired"),+ ({"type": "sdk_error", "error": "Adapter failed"}, "Adapter failed"),+ ],+)+def test_non_list_error_bodies_are_flattened(data, error) -> None:+ assert flatten_error(data) == error+++def test_an_existing_message_is_never_overwritten() -> None:+ data = {"message": {"execution_status": "ERROR", "error": "boom"}}++ assert add_error_message(data) == {+ "message": {"execution_status": "ERROR", "error": "boom"}+ }diff --git a/backend/api_v2/tests/test_docstudio_spec.py b/backend/api_v2/tests/test_docstudio_spec.pyindex a1bc9736e..7d79444a3 100644--- a/backend/api_v2/tests/test_docstudio_spec.py+++ b/backend/api_v2/tests/test_docstudio_spec.py@@ -61,6 +61,10 @@ _KNOWN_EXAMPLE_DIVERGENCES = {("execute", "500", "APIException", "ExecuteResponse"),}+#: The bodies the exception handler produces, and so the only ones whose+#: injected handler example is correct for them.+_HANDLER_SHAPED_SCHEMAS = {"ErrorResponse", "DeploymentErrorResponse"}+#: The operations served by an API deployment, as opposed to the platform-key#: operations that describe the account. They authenticate differently and can#: fail differently, so several checks below split on this.@@ -529,14 +533,14 @@ def test_no_published_example_contradicts_its_own_schema() -> None:replaced, and the artifact contradicts itself in one media-type object.Checked structurally rather than by name: any response declaring a body- other than `ErrorResponse` must carry no handler-shaped example.+ other than a handler-shaped one must carry no handler-shaped example."""matched: set[tuple[str, str, str, str]] = set()for path, method, operation in _operations(_committed()):for code, response in operation["responses"].items():media = response.get("content", {}).get("application/json", {})ref = media.get("schema", {}).get("$ref", "")- if ref.endswith("/ErrorResponse"):+ if ref.split("/")[-1] in _HANDLER_SHAPED_SCHEMAS:continuefor name, example in media.get("examples", {}).items():key = (operation["operationId"], code, name, ref.split("/")[-1])@@ -570,7 +574,8 @@ def test_the_example_contradiction_check_actually_fires() -> None:offending = [namefor name, example in media["examples"].items()- if not ref.endswith("/ErrorResponse") and "errors" in example.get("value", {})+ if ref.split("/")[-1] not in _HANDLER_SHAPED_SCHEMAS+ and "errors" in example.get("value", {})]assert offending == ["Handler"]diff --git a/specs/docstudio-oss.json b/specs/docstudio-oss.jsonindex ea8039b3a..08b71f8e1 100644--- a/specs/docstudio-oss.json+++ b/specs/docstudio-oss.json@@ -131,6 +131,29 @@],"type": "string"},+ "DeploymentErrorResponse": {+ "description": "The body of a rejected execute request.\n\nCarries `message.error` as well, so a client can read the failure from the\nkey an execution reports it in, whatever went wrong.",+ "properties": {+ "errors": {+ "items": {+ "$ref": "#/components/schemas/ErrorDetail"+ },+ "type": "array"+ },+ "message": {+ "$ref": "#/components/schemas/ErrorMessage"+ },+ "type": {+ "$ref": "#/components/schemas/ErrorType"+ }+ },+ "required": [+ "errors",+ "message",+ "type"+ ],+ "type": "object"+ },"ErrorDetail": {"description": "One problem found with the request.","properties": {@@ -155,6 +178,24 @@],"type": "object"},+ "ErrorMessage": {+ "description": "The failure in the same place an execution reports its own.",+ "properties": {+ "error": {+ "description": "Every problem in `errors`, as one readable string.",+ "type": "string"+ },+ "execution_status": {+ "description": "Always `ERROR`.",+ "type": "string"+ }+ },+ "required": [+ "error",+ "execution_status"+ ],+ "type": "object"+ },"ErrorResponse": {"description": "The body of a rejected request.\n\nProduced by the project-wide exception handler, so its shape is the same\nfor every failure listed against an operation.","properties": {@@ -878,7 +919,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/ErrorResponse"+ "$ref": "#/components/schemas/DeploymentErrorResponse"}}},@@ -897,6 +938,10 @@"detail": "Incorrect authentication credentials."}],+ "message": {+ "error": "Incorrect authentication credentials.",+ "execution_status": "ERROR"+ },"type": "client_error"}},@@ -909,12 +954,16 @@"detail": "Authentication credentials were not provided."}],+ "message": {+ "error": "Authentication credentials were not provided.",+ "execution_status": "ERROR"+ },"type": "client_error"}}},"schema": {- "$ref": "#/components/schemas/ErrorResponse"+ "$ref": "#/components/schemas/DeploymentErrorResponse"}}},@@ -933,12 +982,16 @@"detail": "You do not have permission to perform this action."}],+ "message": {+ "error": "You do not have permission to perform this action.",+ "execution_status": "ERROR"+ },"type": "client_error"}}},"schema": {- "$ref": "#/components/schemas/ErrorResponse"+ "$ref": "#/components/schemas/DeploymentErrorResponse"}}},@@ -957,12 +1010,16 @@"detail": "Not found."}],+ "message": {+ "error": "Not found.",+ "execution_status": "ERROR"+ },"type": "client_error"}}},"schema": {- "$ref": "#/components/schemas/ErrorResponse"+ "$ref": "#/components/schemas/DeploymentErrorResponse"}}},@@ -972,7 +1029,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/ErrorResponse"+ "$ref": "#/components/schemas/DeploymentErrorResponse"}}},@@ -1001,12 +1058,16 @@"detail": "Request was throttled."}],+ "message": {+ "error": "Request was throttled.",+ "execution_status": "ERROR"+ },"type": "client_error"}}},"schema": {- "$ref": "#/components/schemas/ErrorResponse"+ "$ref": "#/components/schemas/DeploymentErrorResponse"}}},@@ -1025,6 +1086,10 @@"detail": "A server error occurred."}],+ "message": {+ "error": "A server error occurred.",+ "execution_status": "ERROR"+ },"type": "server_error"}}@@ -1040,7 +1105,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/ErrorResponse"+ "$ref": "#/components/schemas/DeploymentErrorResponse"}}},@@ -1050,7 +1115,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/ErrorResponse"+ "$ref": "#/components/schemas/DeploymentErrorResponse"}}},