Abridge Common Errors

Overview

Comprehensive troubleshooting guide for Abridge clinical documentation integration. Covers authentication failures, EHR connectivity, audio streaming, note generation, and FHIR push errors.

Error Reference

Authentication & Authorization Errors

Session & Encounter Errors

Audio & Transcription Errors

// Common audio streaming diagnostics
async function diagnoseAudioIssues(wsUrl: string): Promise<string[]> {
  const issues: string[] = [];

  // Check WebSocket connectivity
  try {
    const ws = new WebSocket(wsUrl);
    await new Promise((resolve, reject) => {
      ws.onopen = resolve;
      ws.onerror = reject;
      setTimeout(() => reject(new Error('Connection timeout')), 5000);
    });
    ws.close();
  } catch {
    issues.push('WebSocket connection failed — check firewall allows wss:// on port 443');
  }

  // Check audio format requirements
  // Abridge requires: 16kHz, mono, 16-bit PCM little-endian
  const requiredFormat = { sampleRate: 16000, channels: 1, encoding: 'pcm_s16le' };
  issues.push(`Verify audio format: ${JSON.stringify(requiredFormat)}`);

  return issues;
}

Note Generation Errors

// Note generation failure handler
async function handleNoteFailure(sessionId: string, error: any): Promise<void> {
  const status = error.response?.status;
  const code = error.response?.data?.error_code;

  switch (code) {
    case 'INSUFFICIENT_CONTENT':
      console.error('Transcript too short — need at least 30 seconds of clinical conversation');
      break;
    case 'UNSUPPORTED_LANGUAGE':
      console.error('Language not in Abridge supported set (28+ languages)');
      break;
    case 'TEMPLATE_NOT_FOUND':
      console.error('Note template not available — use: soap, hp, progress, procedure');
      break;
    case 'GENERATION_TIMEOUT':
      console.error('Note generation exceeded 120s — complex encounter, retry once');
      break;
    default:
      console.error(`Unknown note error: ${status} ${code}`);
  }
}

FHIR Integration Errors

HIPAA Compliance Errors

// PHI leak detection in error logs
function auditErrorLog(error: any): void {
  const serialized = JSON.stringify(error);

  // Check for accidental PHI in error output
  const phiPatterns = [
    /\b\d{3}-\d{2}-\d{4}\b/,        // SSN
    /\b\d{10}\b/,                     // MRN (10-digit)
    /\b[A-Z][a-z]+\s[A-Z][a-z]+\b/,  // Patient names (heuristic)
    /\b\d{1,2}\/\d{1,2}\/\d{4}\b/,   // DOB
  ];

  for (const pattern of phiPatterns) {
    if (pattern.test(serialized)) {
      console.error('WARNING: Possible PHI detected in error log — redact before logging');
      return;
    }
  }
}

Diagnostic Script

#!/bin/bash
# abridge-diagnostic.sh — Run before opening a support ticket

echo "=== Abridge Integration Diagnostics ==="

# 1. Check credentials
echo "Checking credentials..."
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $ABRIDGE_CLIENT_SECRET" \
  -H "X-Org-Id: $ABRIDGE_ORG_ID" \
  "${ABRIDGE_BASE_URL}/health"

# 2. Check FHIR server
echo "Checking FHIR connectivity..."
curl -s -o /dev/null -w "%{http_code}" \
  "${EPIC_FHIR_BASE_URL}/metadata"

# 3. Check WebSocket
echo "Checking WebSocket..."
curl -s -o /dev/null -w "%{http_code}" \
  --header "Upgrade: websocket" \
  "${ABRIDGE_BASE_URL/http/ws}/ws/health"

echo "=== Diagnostics Complete ==="

Output

• Identified root cause from error code lookup
• Applied targeted fix for the specific error
• HIPAA-safe error logging verified

Resources

• Abridge Platform
• FHIR R4 Operation Outcomes
• HIPAA Breach Notification Rule

Next Steps

For collecting debug evidence for support tickets, see abridge-debug-bundle.