Error catalogue
Stable partner-visible failures → meaning, retryability, and actions.
How to use
- Match HTTP status + code/detail when present.
- Apply retry only if Retry? is Yes.
- Escalate when Escalation says Yes after you exhausted integrator action.
Cross-product HTTP
| HTTP |
Meaning |
Retry? |
Integrator action |
Support action |
Escalation |
| 401 |
Auth failed |
After fixing token/keys |
Refresh JWT / scheme / key |
Verify key material in env |
If keys supposedly rotated |
| 409 |
Conflict (e.g. active recon session) |
After backoff / new session |
New session_id or wait |
Check period lock |
Rare |
| 422 |
Validation / missing header |
No (same body) |
Fix payload/headers |
Spot-check schema drift |
If schema disagrees with OpenAPI |
| 4xx business |
Rejected check / contract |
Usually No |
Fix business input |
Correlate ids |
If systematic |
| 5xx |
Server/dependency |
Yes with backoff |
Retry per tables |
Check dependency health |
Persistent 5xx |
| Timeout |
Uncertain |
Yes cautiously |
Idempotent retry only |
Trace by session/tx id |
Persistent |
Fraud-specific codes
| Code / detail |
HTTP |
Meaning |
Retry same body? |
Integrator |
Support |
Escalation |
| Invalid authorization scheme |
401 |
Not ApiKey |
After fix |
Use ApiKey |
— |
No |
| Token verification failed |
401 |
Bad/expired/wrong claims |
After new token |
Mint/verify claims |
Key mismatch |
If widespread |
Missing x-tenant-id |
422 |
Tenant header required |
After adding header |
Send header |
— |
No |
AMBIGUOUS_PREDICTION_CONTRACT |
compose fail |
Mixed ML+rule identity |
No |
Fix emitter |
Contract review |
Yes if producer bug |
ML_SCORE_TIER_CONFLICT |
compose fail |
Score vs tier mismatch |
No |
Align bands/policy |
Owner decision on bands |
Yes (known handoff defect) |
KYC
| Situation |
Retry? |
Integrator |
Support |
Escalation |
| Vendor timeout / 5xx |
Cautious yes |
Backoff; avoid duplicate paid calls |
Vendor status |
Persistent vendor outage |
| 200 with no-match / uncertain |
No |
Show uncertainty to ops |
— |
Policy questions |
| Auth at gateway |
After credential fix |
Fix gateway token/mTLS |
Ingress config |
Misprovisioned env |
Reconciliation
| Situation |
Retry? |
Integrator |
Support |
Escalation |
| Ingest 409 active session |
After wait / new session |
Respect period lock |
Lock ownership |
Stuck lock |
Resolve without resolution_request_id on messaging |
No until id added |
Always send id |
— |
No |
| Duplicate trigger ignored |
N/A |
Use new session if intentional rerun |
Trigger guard |
No |
| Wrong template / matching method |
No |
Fix template |
User-facing error copy |
No |