TIKA-4753 - improve oom/timeout/crash msg

[tballison]

Thanks for your contribution to Apache Tika! Your help is appreciated!

Before opening the pull request, please verify that

• there is an open issue on the Tika issue tracker which describes the problem or the improvement. We cannot accept pull requests without an issue because the change wouldn't be listed in the release notes.
• the issue ID (TIKA-XXXX)
  • is referenced in the title of the pull request
  • and placed in front of your commit messages surrounded by square brackets ([TIKA-XXXX] Issue or pull request title)
• commits are squashed into a single one (or few commits for larger changes)
• Tika is successfully built and unit tests pass by running ./mvnw clean test
• there should be no conflicts when merging the pull request branch into the recent main branch. If there are conflicts, please try to rebase the pull request branch on top of a freshly pulled main branch
• if you add new module that downstream users will depend upon add it to relevant group in tika-bom/pom.xml.

We will be able to faster integrate your pull request if these conditions are met. If you have any questions how to fix your problem or about using Tika in general, please sign up for the Tika mailing list. Thanks!

[Copilot]

Pull request overview

This PR updates tika-server’s Pipes-based error handling so process failures (OOM/timeout/crash) return more machine-readable JSON bodies and aligns HTTP status codes (notably mapping UNSPECIFIED_CRASH to 503) with the “transient process failure” category. It also updates integration tests and user-facing docs to describe the new error response format.

Changes:

• Return JSON error bodies ({"status": "...", "message": "..."}) from Pipes-based server endpoints on failures.
• Treat UNSPECIFIED_CRASH as 503 Service Unavailable (same class as TIMEOUT/OOM) and update integration tests accordingly.
• Document the new JSON error response shape and the HTTP-status-to-status mapping.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
tika-server/tika-server-core/src/test/java/org/apache/tika/server/core/TikaServerIntegrationTest.java	Updates integration tests to assert JSON error bodies and 503 for UNSPECIFIED_CRASH.
tika-server/tika-server-core/src/main/java/org/apache/tika/server/core/resource/PipesParsingHelper.java	Builds and returns JSON error responses for PipesResult failures; refines status mapping.
docs/modules/ROOT/pages/using-tika/server/index.adoc	Adds an “Error Responses” section documenting JSON error bodies and mappings.
docs/modules/ROOT/pages/migration-to-4x/migrating-tika-server-4x.adoc	Notes the change from plain-text to JSON error bodies and the UNSPECIFIED_CRASH status-code change.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.