Diagnose a stuck claim 🚨

Outcome

A claim that is stuck at any lifecycle stage has a documented root cause and a clear next action — submit, fix and rebuild, or escalate.

Prerequisites

• billing.claim.read (status inspection) and billing.claim.write (any state-changing action).
• psql access for direct DB inspection.
• Access to the EDI Gateway logs.

Common stuck states

Status	Meaning	Investigation
CREATED	Not yet built	Confirm charges are validated; run POST /claims/build.
BUILT	Built but not submitted	Check EDI Gateway for submission errors.
SUBMITTED	Waiting for acknowledgment	Check 999/TA1 response; check SFTP polling.
REJECTED	Payer rejected (999)	Inspect error_details; fix and resubmit.
DENIED	Payer denied payment	See Denials and appeals.

Diagnostic flow

Steps

1. Check current claim status:

   curl "http://localhost:3002/claims/<claim_id>"

2. Read the status history:

   SELECT c.claim_id, c.status_current,
          csh.status, csh.changed_at, csh.reason
   FROM billing.claim c
   JOIN billing.claim_status_history csh ON c.claim_id = csh.claim_id
   WHERE c.claim_id = '<claim_id>'
   ORDER BY csh.changed_at;

   The history tells you when the claim got stuck, not just where.

3. Inspect EDI transactions for this claim:

   SELECT et.edi_transaction_id, et.direction, et.tx_type, et.status,
          et.error_details, et.retry_count, et.created_at
   FROM billing.edi_transaction et
   JOIN billing.edi_transaction_claim etc
     ON et.edi_transaction_id = etc.edi_transaction_id
   WHERE etc.claim_id = '<claim_id>'
   ORDER BY et.created_at DESC;

   Patterns:

   Pattern	Meaning	Next
   Outbound SUBMITTED, no inbound 999	Acknowledgment never received	Handle SFTP failure
   Outbound ERROR with retry_count >= 3	Stuck in retry loop	Fix root cause; manually replay
   No edi_transaction rows at all	Routing failed; claim never built into a batch	Check routing rules simulator

4. Take the appropriate action based on status:

   Status	Action
   CREATED	Run POST /claims/build. If it fails, the response carries the validation issue.
   BUILT	Replay submission: POST /edi/admin/replay/<edi_transaction_id>
   SUBMITTED	Check SFTP poller; see Handle SFTP failure.
   REJECTED	Read edi_transaction.error_details; fix charges/configuration; rebuild.
   DENIED	Move to Denials and appeals.

Validation

Check	Expected
claim.status_current	Advanced past stuck state
edi_transaction row	Latest transaction has clean error_details
claim_status_history	New row with the recovery transition

Troubleshooting

Symptom	Cause	Fix
POST /claims/build fails with CHARGES_NOT_VALIDATED	Charges have validation errors	Inspect charge.errors; fix and revalidate.
Replay returns 200 but transaction stays ERROR	Underlying batch malformed	Look at error_details — typically a companion-guide validation failure.
Claim moves to SUBMITTED then back to BUILT	TA1/999 rejection not detected	Check the 999 parser; the claim shouldn't auto-revert without a status reason.
Multiple claims stuck simultaneously	Routing or partner outage	See Submission routing rules and SFTP failure.

Cross-references

• Denials and appeals — for DENIED claims.
• Handle SFTP failure — for SUBMITTING/SUBMITTED issues.
• Distributed tracing — to follow a claim's correlation id across services.

Next

3.2 — Manage denials and appeals