gabrielmoreira 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
- Identify affected meeting/action state and collect only opaque IDs, status, configuration version, and timing.
- Validate scope, access, consent, mapping, and rate-limit conditions before applying a correction.
- 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
Next Steps
For diagnostics, see fathom-debug-bundle.