Troubleshooting
Start with the logs: every message’s journey is journaled (received →
stored/rejected, mdn-received, delivered, retry-scheduled, …)
with the partnership id and message id on every line.
The partner’s message is rejected
The disposition in our negative receipt (and the rejected journal
entry) says why:
| Disposition | Meaning | Usual cause |
|---|---|---|
authentication-failed | no partnership matched AS2-From/AS2-To | identifier typo, case mismatch, or the partnership is missing — check both sides’ AS2 names character-for-character |
insufficient-message-security | message lacked a layer the partnership requires | partner sent unsigned/unencrypted; either they misconfigured, or your security floor is stricter than agreed |
decryption-failed | could not decrypt | partner encrypted to the wrong (old?) certificate; or an incompatible cipher (CAST5/IDEA with Java partners — use 3DES/AES) |
integrity-check-failed | signature did not verify | wrong partner certificate installed on our side, or the partner rotated certificates |
decompression-failed | bad or doubled compression | double compression is rejected by design |
unsupported format / unsupported MIC-algorithms | receipt request we cannot honor | partner asked for a signature protocol/digest outside the supported set |
unsupported receipt-delivery-option | async receipt requested but not available on this deployment | deployment/licensing does not include async MDNs |
error-storing-transaction | storage backend failed | check the storage backend’s health; the partner will retry |
Our send fails
- HTTP errors: 4xx (except 408/429) are treated as permanent — check
URL, HTTP auth, and that the partner has your partnership configured.
5xx/408/429/connection errors retry with exponential backoff; watch
retry-scheduledand the finaldeliveredorgave-up. gave-upjournal entries carry the last error text and attempt count.
Receipts mismatch (mdn-mic-mismatch)
Work through the checklist in MDN receipts — it is almost always non-mirrored security attributes or a counterpart quirk listed in Working with specific products.
The server answers 503 to partners
Check /healthz:
degraded: unlicensed/degraded: license expired— see Installing your license.- Body
okbut 503s under load — you may have hit a configured daily message quota; the 503 carries aRetry-Afterheader and partners’ retry logic rides it out.
The server won’t start
The error printed at startup is specific by design:
- license invalid → the exact verification failure
- configuration exceeds entitlements → the partnership and entitlement named
- storage unreachable → connect errors surface at boot (deliberately — fail at boot, not at the first message)
- a certificate expired → named alias and dates
Getting help
Include: the journal lines for one affected message id, the negative MDN text (if any), your partnership definition (redact keys/passwords), and both sides’ declared security attributes. That is nearly always enough to diagnose an interop issue on the first round-trip.