Format Java Backend Exceptions

[Mythicaeda]

• Tickets addressed: Closes Reduce the Types of Exceptions PermissionsService throws #1771 and closes Implement common HTTP error message formats for all Aerie services #1732
• Review: By commit
• Merge strategy: Merge (no squash)

Description

This PR does three things:

1. Make PermissionsService only throw a singular exception to reduce duplicated code in the services that use it
2. Update how Exceptions thrown in the Java endpoints are formatted to be united.
3. Ensure that Hasura returns the entire formatted exception in the extensions object

Number 2) is accomplished by pulling FormattedError out into the parsing-utils library, then creating service-specific subclasses to handle service-specific exceptions.

Verification

E2E Tests were updated to reflect the updates to the error messages.

I did some manual tests with the UI. In these tests, I started a debugger in the backend with a breakpoint set at the start of the Hasura Action Handler code. After submitting the request via the UI, I would go in and remove data from the database to force the backend pre-checks to fail. I'd then resume the backend and observe that 1) the backend was sending the information correctly and 2) how the UI was parsing the response.

What I observed was:

• for Hasura Action endpoints, the backend is correctly putting the formatted exception in the extensions object
• the UI is reading this extensions object and is able to extract data, service, and timestamp out of it. It's unclear if it's using the top-level message field or the one in the extensions object, but that doesn't matter since they contain the same string.
• the UI is not reading the type field out of the extensions object, instead using a generic ERROR type. The type field is present in extensions object
• if scheduling, simulation, or constraints throw an exception (rather than failing), the exception is placed under the generic LOGS tab rather than being sorted into the correct category.

Example:
Server Response:

{
	"errors": [
		{
			"extensions": {
				"data": {
					"specification_id": 659
				},
				"message": "Could not check permissions on scheduling specification 659: specification does not exist.",
				"service": "aerie_permissions",
				"timestamp": "2026-05-18T16:10:49.084229462Z",
				"trace": <TRACE REMOVED BY ME FOR CONCISENESS>,
				"type": "NO_SUCH_SCHEDULING_SPECIFICATION"
			},
			"message": "Could not check permissions on scheduling specification 659: specification does not exist."
		}
	]
}

UI Logs:

Documentation

Future work

[dandelany]

@Mythicaeda will do some smoke testing of this against the current version of the UI to make sure the new message format is fully supported

[dandelany]

Discussed this one with @Mythicaeda yesterday and we realized that the endpoints used by Hasura queries (listed in deployment/hasura/metadata/actions.yaml) need to have their error payloads wrapped in the extensions structure as noted in #1732 (see "Endpoints accessed by Hasura Actions")

[dandelany]

FYI @Mythicaeda I merged develop into this branch and fixed some conflicts with the "simultaneous edit" work in bd10a8b and 8959452, tests are passing - though scans are failing again (should be fixed by #1850). I'm working on doing the same with the UI branch & smoke testing the merged branches

[dandelany]

Thanks @Mythicaeda - this required some more changes on the UI than we originally thought, but I think we're finally there. This has been reviewed and tested with the latest NASA-AMMOS/plandev-ui#1933 and they are ready to merge (together)

[sonarqubecloud]

Quality Gate failed

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

💡 Need a hand with PR review? Try Gitar by Sonar!