---
name: fathom-common-errors
description: 'Diagnose and fix Fathom API errors including auth failures and missing
  data.

  Use when API calls fail, transcripts are empty, or webhooks are not firing.

  Trigger with phrases like "fathom error", "fathom not working",

  "fathom api failure", "fix fathom".

  '
allowed-tools: Read, Bash(curl:*), Grep
version: 1.6.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- meeting-intelligence
- ai-notes
- fathom
compatibility: Designed for Claude Code
---
# 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:

```bash
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

```bash
# 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](https://help.fathom.video)
- [Fathom API Docs](https://developers.fathom.ai)

## Next Steps

For diagnostics, see `fathom-debug-bundle`.


---
Source attribution: jeremylongshore
Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/fathom-pack/skills/fathom-common-errors/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2025 Jeremy Longshore

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: jeremylongshore
Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/fathom-pack/skills/fathom-common-errors/SKILL.md
Attribution basis: Source repository record

Fields of work: Sales, Customer Support
Roles: Customer Success Manager, Sales Development Rep (SDR), Technical Support
Specialties: API, Design, Frontend, Remotion, Testing
Tools: Fathom
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 812d0728b2f4e0780e6ea016012252abaafdc76a5f9cfb907df48867f70cd1b6