fix: improve error handling for invalid input in processing endpoints (#71)

Author: lfoppiano

README.md

@@ -206,7 +206,13 @@ This dataset is the result of the extraction of software mentions from the set o
 
 ### Error handling
 
-The processing endpoints (`processSoftwareText`, `annotateSoftwarePDF`, `annotateSoftwareXML`, `annotateSoftwareTEI`) **fail loud**: when an internal step fails — for instance the context classifier, or the parsing of an XML/TEI input — the service returns an HTTP `500` together with a descriptive error message, instead of silently returning an empty or partial `200` response. A `204` (no content) is reserved for the case where the input is valid but genuinely contains nothing to extract. Clients should therefore treat a `500` as a real processing failure to surface or retry, not as "no mentions found".
+The processing endpoints (`processSoftwareText`, `annotateSoftwarePDF`, `annotateSoftwareXML`, `annotateSoftwareTEI`) **fail loud** instead of silently returning an empty or partial `200` response, and distinguish *who* is at fault:
+
+- **`400 Bad Request`** — the submitted document is invalid input the service cannot process: a malformed or unparseable PDF, publisher XML or TEI file (e.g. not well-formed XML, an empty upload, or a PDF with no extractable content). The response body carries a descriptive message.
+- **`500 Internal Server Error`** — a genuine internal failure of the pipeline (model inference, context classification, etc.) on otherwise-valid input.
+- **`204 No Content`** — the input is valid but genuinely contains nothing to extract.
+
+Clients should treat a `400` as "fix the input and resubmit" and a `500` as a real server-side failure to surface or retry — neither should be read as "no mentions found".
 
 ### /service/processSoftwareText
 

src/main/java/org/grobid/core/engines/SoftwareParser.java

@@ -23,6 +23,7 @@
 import org.grobid.core.engines.label.TaggingLabels;
 import org.grobid.core.engines.tagging.GrobidCRFEngine;
 import org.grobid.core.exceptions.GrobidException;
+import org.grobid.core.exceptions.GrobidExceptionStatus;
 import org.grobid.core.factory.GrobidFactory;
 import org.grobid.core.features.FeatureFactory;
 import org.grobid.core.features.FeaturesVectorSoftware;
@@ -825,7 +826,12 @@ public Pair<List<SoftwareEntity>, Document> processPDF(
             entities = SoftwareContextClassifier.getInstance(softwareConfiguration).classifyDocumentContexts(entities);
 
         } catch (Exception e) {
-            throw new GrobidException("Cannot process pdf file: " + file.getPath(), e);
+            // preserve the underlying status (e.g. BAD_INPUT_DATA for a corrupt PDF raised by GROBID)
+            // so that invalid input is still reported as such rather than downgraded to a generic error
+            GrobidExceptionStatus status = (e instanceof GrobidException)
+                ? ((GrobidException) e).getStatus()
+                : GrobidExceptionStatus.GENERAL;
+            throw new GrobidException("Cannot process pdf file: " + file.getPath(), e, status);
         }
 
         return Pair.of(entities, doc);
@@ -2487,27 +2493,25 @@ public int boostrapTrainingPDF(String inputDirectory,
     public Triple<Optional<ArticleBiblio>, List<SoftwareEntity>, List<BibDataSet>> processXML(File file,
                                                                                               boolean disambiguate,
                                                                                               boolean addParagraphContext) throws IOException {
-        Triple<Optional<ArticleBiblio>, List<SoftwareEntity>, List<BibDataSet>> resultExtraction = null;
+        org.w3c.dom.Document document;
         try {
             String tei = processXML(file);
             DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
             factory.setNamespaceAware(true);
             DocumentBuilder builder = factory.newDocumentBuilder();
             //tei = avoidDomParserAttributeBug(tei);
 
-            org.w3c.dom.Document document = builder.parse(new InputSource(new StringReader(tei)));
+            document = builder.parse(new InputSource(new StringReader(tei)));
             //document.getDocumentElement().normalize();
-
-            resultExtraction = processTEIDocument(document, disambiguate, addParagraphContext);
-
             //tei = restoreDomParserAttributeBug(tei);
 
         } catch (final Exception exp) {
-            throw new GrobidException("An error occurred while processing the following XML file: "
-                + file.getPath(), exp);
+            // a failure to transform/parse the input is a client error: the submitted XML is invalid
+            throw new GrobidException("An error occurred while parsing the following XML file: "
+                + file.getPath(), exp, GrobidExceptionStatus.BAD_INPUT_DATA);
         }
 
-        return resultExtraction;
+        return processTEIDocument(document, disambiguate, addParagraphContext);
     }
 
 
@@ -2519,22 +2523,22 @@ public Triple<Optional<ArticleBiblio>, List<SoftwareEntity>, List<BibDataSet>> p
         boolean disambiguate,
         boolean addParagraphContext
     ) throws IOException {
-        Triple<Optional<ArticleBiblio>, List<SoftwareEntity>, List<BibDataSet>> resultExtraction = null;
+        org.w3c.dom.Document document;
         try {
             DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
             factory.setNamespaceAware(true);
             DocumentBuilder builder = factory.newDocumentBuilder();
-            org.w3c.dom.Document document = builder.parse(file);
+            document = builder.parse(file);
             //document.getDocumentElement().normalize();
-            resultExtraction = processTEIDocument(document, disambiguate, addParagraphContext);
             //tei = restoreDomParserAttributeBug(tei);
 
         } catch (final Exception exp) {
-            throw new GrobidException("An error occurred while processing the following TEI file: "
-                + file.getPath(), exp);
+            // a failure to parse the input is a client error: the submitted TEI is invalid
+            throw new GrobidException("An error occurred while parsing the following TEI file: "
+                + file.getPath(), exp, GrobidExceptionStatus.BAD_INPUT_DATA);
         }
 
-        return resultExtraction;
+        return processTEIDocument(document, disambiguate, addParagraphContext);
     }
 
     /**

src/main/java/org/grobid/service/controller/SoftwareProcessFile.java

@@ -15,6 +15,8 @@
 import org.grobid.core.engines.Engine;
 import org.grobid.core.engines.SoftwareParser;
 import org.grobid.core.engines.config.GrobidAnalysisConfig;
+import org.grobid.core.exceptions.GrobidException;
+import org.grobid.core.exceptions.GrobidExceptionStatus;
 import org.grobid.core.factory.GrobidFactory;
 import org.grobid.core.layout.Page;
 import org.grobid.core.utilities.IOUtilities;
@@ -48,6 +50,21 @@ public class SoftwareProcessFile {
     public SoftwareProcessFile() {
     }
 
+    /**
+     * Build the error response for a processing failure. Failures caused by invalid input
+     * (a {@link GrobidException} flagged as {@link GrobidExceptionStatus#BAD_INPUT_DATA}, e.g. a
+     * malformed/unparseable PDF, XML or TEI) are reported as HTTP 400; anything else is a genuine
+     * internal error and reported as HTTP 500.
+     */
+    private static Response buildErrorResponse(Exception exp) {
+        Status httpStatus = Status.INTERNAL_SERVER_ERROR;
+        if (exp instanceof GrobidException
+            && ((GrobidException) exp).getStatus() == GrobidExceptionStatus.BAD_INPUT_DATA) {
+            httpStatus = Status.BAD_REQUEST;
+        }
+        return Response.status(httpStatus).entity(exp.getMessage()).build();
+    }
+
     /**
      * Uploads the origin PDF, process it and return PDF annotations for the software mention objects in JSON.
      *
@@ -142,7 +159,7 @@ public static Response processPDFAnnotation(final InputStream inputStream,
             response = Response.status(Status.SERVICE_UNAVAILABLE).build();
         } catch (Exception exp) {
             LOGGER.error("An unexpected exception occurs. ", exp);
-            response = Response.status(Status.INTERNAL_SERVER_ERROR).entity(exp.getMessage()).build();
+            response = buildErrorResponse(exp);
         } finally {
             IOUtilities.removeTempFile(originFile);
         }
@@ -243,7 +260,7 @@ public static Response processPDFAnnotation(final InputStream inputStream,
             response = Response.status(Status.SERVICE_UNAVAILABLE).build();
         } catch (Exception exp) {
             LOGGER.error("An unexpected exception occurs. ", exp);
-            response = Response.status(Status.INTERNAL_SERVER_ERROR).entity(exp.getMessage()).build();
+            response = buildErrorResponse(exp);
         } finally {
             IOUtilities.removeTempFile(tmpPdf);
         }
@@ -328,7 +345,7 @@ public static Response extractXML(final InputStream inputStream,
             response = Response.status(Status.SERVICE_UNAVAILABLE).build();
         } catch (Exception exp) {
             LOGGER.error("An unexpected exception occurs. ", exp);
-            response = Response.status(Status.INTERNAL_SERVER_ERROR).entity(exp.getMessage()).build();
+            response = buildErrorResponse(exp);
         } finally {
             IOUtilities.removeTempFile(originFile);
         }
@@ -420,7 +437,7 @@ public static Response extractTEI(
             response = Response.status(Status.SERVICE_UNAVAILABLE).build();
         } catch (Exception exp) {
             LOGGER.error("An unexpected exception occurs. ", exp);
-            response = Response.status(Status.INTERNAL_SERVER_ERROR).entity(exp.getMessage()).build();
+            response = buildErrorResponse(exp);
         } finally {
             IOUtilities.removeTempFile(originFile);
         }