Errors, retries, and correlation
Partner-oriented guidance for cross-cutting behaviour.
Fraud
| Concern |
Guidance |
| Contract errors on report compose |
AMBIGUOUS_PREDICTION_CONTRACT, ML_SCORE_TIER_CONFLICT, and related validation failures — fix the emitter; do not retry the same bad body expecting success |
| Dashboard handoff failure |
Safe to rely on platform redelivery only if your environment is configured that way (confirm with MasteryHive) |
| Stream auth errors |
401 — refresh token; check ApiKey scheme (not Bearer) |
| Correlation IDs |
Prefer transaction_id / tenant scope in your logs; a single global partner correlation header is not guaranteed |
| Idempotency on core TM paths |
Design for at-least-once delivery; confirm any environment-specific idempotency keys with MasteryHive |
KYC / KYB
| Concern |
Guidance |
| Vendor retries |
Server-side retries may exist; callers should still treat timeouts as uncertain |
| Correlation IDs |
No standard partner correlation header is guaranteed — use userId and your own request ids |
| Idempotency |
Not a documented partner key on KYC routes — avoid duplicate expensive vendor calls client-side |
Reconciliation
| Concern |
Guidance |
| Session identity |
Carry stable session_id across retries of the same business run |
| Exception resolve idempotency |
Always send a stable resolution_request_id when supported |
| Match upsert idempotency |
Replays should not duplicate matches for the same business keys |
| Overwrite vs merge |
Choose on_existing_action deliberately |
| Correlation IDs |
Prefer session / partner / tenant / task ids over inventing a new header |