Fathom Common Errors

Overview

Diagnose Fathom meeting, transcript, integration, CRM-sync, and authorization issues with minimal redacted evidence and reversible fixes.

Prerequisites

• A bounded non-sensitive reproduction, environment/version, consent/data policy, and approved diagnostic channel.

Instructions

1. Identify affected meeting/action state and collect only opaque IDs, status, configuration version, and timing.
2. Validate scope, access, consent, mapping, and rate-limit conditions before applying a correction.
3. Test the smallest safe fix with synthetic records and document the verified result.

Output

• A classified failure with redacted evidence, bounded remediation, owner, and verified recovery/escalation.

Error Handling

Condition	Safe response
Consent or access is unclear	Stop processing/sharing and verify ownership/policy.
CRM mapping is wrong	Pause sync and correct/test mapping before replay.
Duplicate action occurs	Deduplicate by stable ID; do not resend automatically.

Examples

For a missing follow-up, verify the synthetic meeting's action ID, consent state, mapping version, and CRM result in development. Escalate with redacted evidence if unresolved; do not inspect or share a customer recording to troubleshoot it.

Error Reference

1. 401 Unauthorized

Fix: Regenerate API key at Settings > Integrations > API Access.

2. 429 Rate Limited

Limit: 60 calls per minute across all API keys. Fix: Implement exponential backoff. Batch requests.

3. Empty Transcript

Causes: Meeting still processing, recording too short, or audio quality issues. Fix: Wait 5-10 minutes after recording. Check recording in Fathom UI.

4. Missing Summary

Cause: AI processing not complete. Fix: Poll the recording endpoint until summary is available.

5. Webhook Not Firing

Fix: Verify webhook URL in Settings > Integrations > Webhooks. Test with:

curl -X POST https://your-url.com/webhooks/fathom \
  -H "Content-Type: application/json" \
  -d '{"type": "test"}'

6. OAuth Token Expired

Fix: Refresh the access token using your refresh token.

Quick Diagnostics

# Test API key
curl -s -o /dev/null -w "%{http_code}" -H "X-Api-Key: ${FATHOM_API_KEY}" \
  https://api.fathom.ai/external/v1/meetings?limit=1

Resources

• Fathom Help Center
• Fathom API Docs

Next Steps

For diagnostics, see fathom-debug-bundle.