Error handling notes

Error Handling and Message Flow
The integration endpoints in this system are designed to receive HTTP POST requests which contain structured JSON payloads. These endpoints act as interfaces between client applications and internal services. Upon successful validation, incoming requests are processed and subsequently forwarded to downstream integration using messages.

Payload Validation
Each request undergoes an initial validation phase, which ensures the presence and correctness of all required fields. If any required data is missing or malformed, the API responds immediately with a 400 Bad Request status, accompanied by a descriptive error message. These validation errors are strictly related to the structure and completeness of the request payload.

For example, a request to ../integrations/authenticate missing fields such as GameMode, OperatorPlayerId, or OperatorPlayerSession will result in a JSON error response like the following:

{
    "errors": {
        "GameMode": [
            "The GameMode field is required."
        ],
        "OperatorPlayerId": [
            "The OperatorPlayerId field is required."
        ],
        "OperatorPlayerSession": [
            "The OperatorPlayerSession field is required."
        ]
      	...
    },
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-94321c179b3f49c286cae93fd6a21e94-6d129d1e1425ac10-01"
}

This early validation step helps ensure that only structurally valid requests proceed to downstream processing.

Another example would be the common error shared between all endpoints:

{
	"errorCode": "IO1",
	"message": "No integration could be found for the supplied operator and environment."
}

This indicates that the message cannot be passed to the operator integration because he hasn't deployed to the target environment.

Internal Message Handling
Once a request passes validation, it is not processed synchronously. Instead, it is transformed into a message and published to the target integration. This decouples the request-handling logic from the actual business processing, which occurs asynchronously in the operator integration.

Error Propagation
Because processing continues in downstream integration, any business logic errors (e.g., failed authentication, invalid operator state, or downstream service failures) are not returned in the initial HTTP response. Instead, such errors are captured by the integration and handled separately.

If a downstream integration encounters an issue with the message content or fails to process it successfully, it will publish a rejection message(documented in each endpoint). These rejected messages are available for monitoring, retry logic, or audit purposes and are not exposed directly to the client through the original HTTP response.