Skip to content

LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows

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.py
index 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 ApiDeploymentDTORegistry
from api_v2.constants import ApiExecution
from api_v2.deployment_helper import DeploymentHelper
from api_v2.dto import DeploymentExecutionDTO
+from api_v2.error_message import add_error_message
from api_v2.exceptions import (
NoActiveAPIKeyError,
RateLimitExceeded,
@@ -41,6 +42,7 @@ from api_v2.models import APIDeployment
from api_v2.openapi_schema import (
API_DEPLOYMENT_LIST_SCHEMA,
DEPLOYMENT_EXECUTION_SCHEMA,
+ DeploymentAutoSchema,
)
from api_v2.rate_limiter import APIDeploymentRateLimiter
from api_v2.serializers import (
@@ -61,6 +63,8 @@ logger = logging.getLogger(__name__)
@DEPLOYMENT_EXECUTION_SCHEMA
class 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 = True
return 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_key
def post(
self,
diff --git a/backend/api_v2/error_message.py b/backend/api_v2/error_message.py
new file mode 100644
index 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 data
diff --git a/backend/api_v2/openapi_schema.py b/backend/api_v2/openapi_schema.py
index 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 StandardizedErrorsAutoSchema
from platform_api.openapi_schema import PlatformKeyError
from rest_framework import serializers
+from api_v2.error_message import add_error_message
from api_v2.models import API_NAME_MAX_LENGTH, DESCRIPTION_MAX_LENGTH
from 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.py
index 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.py
new file mode 100644
index 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.py
index 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:
continue
for 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 = [
name
for 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.json
index 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"
}
}
},