Error-to-action matrix
Partner-safe mapping from common failures to caller action, support action, engineering escalation, and retry. Complements the error catalogue.
Legend
| Column |
Meaning |
| Caller |
What the integrator / client backend should do |
| Support |
What MasteryHive support does with triage evidence |
| Eng escalate? |
When to page engineering |
| Retry? |
Safe to retry same logical request? |
Fraud
| Symptom / code |
Caller |
Support |
Eng? |
Retry? |
| 401 wrong scheme / bad JWT |
Fix ApiKey + claims/keys — auth tutorial |
Confirm key exchange env |
If widespread after rotation |
After new token |
422 missing x-tenant-id |
Send header |
— |
No |
After fix |
| Scoring 5xx / timeout |
Backoff; correlate transaction_id |
Check service health (internal) |
Persistent |
Cautious yes |
ML_SCORE_TIER_CONFLICT / AMBIGUOUS_PREDICTION_CONTRACT |
Do not retry same body; fix emitter / await policy alignment |
Log as contract defect |
Yes (known handoff class) |
No same body |
| 200 score, no report |
Follow missing report |
Verify callback reachability with eng |
If callback healthy but silent |
Rescore only after cause fixed |
| Case-rule 400/500 |
Fix payload; see Case management |
Correlate |
Persistent |
After fix |
KYC / KYB
| Symptom |
Caller |
Support |
Eng? |
Retry? |
| Gateway auth failure |
Fix env credentials |
Ingress/provisioning |
Misprovisioned env |
After fix |
| 5xx / timeout |
Treat as uncertain; backoff |
Vendor/status check |
Vendor outage |
Cautious; avoid duplicate billed calls |
| 200 no-match |
Show as negative verification |
— |
Policy only |
No |
| 200 uncertain / partial vendor fields |
Show uncertain — do not coerce pass |
— |
Rare |
No |
| Provider outage pattern |
Fail closed or queue per your policy |
Follow internal outage runbook |
Yes if confirmed |
After provider recovery |
Reconciliation
| Symptom |
Caller |
Support |
Eng? |
Retry? |
| 409 active session / period lock |
Wait or new session_id |
Check stuck lock (internal) |
Stuck lock |
New session preferred |
| Ingest 422 |
Fix scope/template/enums |
Schema drift check |
If OpenAPI wrong |
After fix |
| Status not terminal |
Poll status; avoid same-session hammer |
Stuck-session runbook (internal) |
Yes if stalled |
Prefer guidance from support |
Resolve without resolution_request_id (messaging) |
Always send stable id |
— |
No |
After adding id |
| Duplicate trigger no-op |
Use new session if intentional rerun |
Explain trigger guard |
No |
New session |
Case management (rule scoring only)
| Symptom |
Caller |
Support |
Eng? |
Retry? |
| Expecting durable case desk from AI score |
Read Case Management product |
Clarify scope |
No |
N/A |
| 401/422 on case-rule route |
Same as Fraud scoring auth |
— |
No |
After fix |