Skip to main content
AI/MLjeremylongshore

fathom-common-errors

'Diagnose and fix Fathom API errors including auth failures and missing

Stars
2,267
Source
jeremylongshore/claude-code-plugins-plus-skills
Updated
2026-05-31
Slug
jeremylongshore--claude-code-plugins-plus-skills--fathom-common-errors
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/jeremylongshore/claude-code-plugins-plus-skills/HEAD/plugins/saas-packs/fathom-pack/skills/fathom-common-errors/SKILL.md -o .claude/skills/fathom-common-errors.md

Drops the SKILL.md into .claude/skills/fathom-common-errors.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

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

Next Steps

For diagnostics, see fathom-debug-bundle.