6. Malformed request / MessageFormat errors

Symptom

Requests are rejected immediately with ErrorCondition: MessageFormat, or the terminal returns an EventNotification with EventToNotify: "Reject" instead of the expected response.

What the two rejections mean

  • MessageFormat — the message parsed, but violates the contract: a missing mandatory field, a wrong type (number where a string is expected — amounts are strings, e.g. "11.99"), or an invalid enum value.
  • EventNotification: Reject — the message could not be parsed at all: broken JSON, wrong envelope for the transport, or a body that does not match the endpoint.

Checklist

  1. Validate your JSON mechanically before blaming the contract.
  2. Check the MessageHeader — all of ProtocolVersion ("3.1"), MessageClass, MessageCategory, MessageType, ServiceID, SaleID, POIID present, and MessageCategory matching the endpoint (Payment body on /payment).
  3. Amounts as strings, timestamps ISO 8601 with timezone — the two most common type errors.
  4. Right shape for the transport — flat JSON on HTTP; SaleToPOIRequest envelope only on the socket. An enveloped message on HTTP is a classic Reject.
  5. Compare against the spec's example for your operation on api-hub — diff your payload against it field by field; the divergence is usually visible in seconds.

Do not retry as-is

MessageFormat is deterministic: the same request will fail the same way. Fix the payload; retrying is noise in everyone's logs.