PIL-1600 Add Error Response Examples to API Specifications

[JamesMMiller]

This PR updates the API specifications by adding standardized error response examples to app.routes and generated a new application.yaml from it.

Note: During these updates, some inconsistencies in our API error handling were identified but not addressed in this PR. Additionally, each endpoint may require specific 422 Unprocessable Entity error examples as they are a different set per endpoint.

Changes

• conf/app.routes:
  • Added 401 Unauthorized error responses with a generic message.
  • Provided examples for InvalidJson, EmptyRequestBody, GenericServerError, and NoSubscriptionData.
  • Generated a new application.yaml from this

Inconsistencies Found

• Malformed Response Handling:

  • BTN endpoints return detailed JSON errors (UnparsableResponse) to the client, while UKTR endpoints use a generic "Internal Server Error" (UnexpectedResponse).

• AuthenticationError Usage:

  • All authentication errors currently map to 401 Unauthorized, though some might be more appropriate as 403 Forbidden or 400 Bad Request.

These inconsistencies should probably be addressed in future PRs to ensure uniform error responses across the API.

[platops-pr-bot]

• Your service can now use Java 21. Please set JavaType.OPENJDK_JRE21 in build-jobs - See confluence https://confluence.tools.tax.service.gov.uk/x/xIACM