Troubleshooting

Missing key: set FIREFLIES_API_KEY, pass --api-key, or use --dry-run. Help and local webhook checks need no key.
Authentication failure: verify Authorization: Bearer <key> and regenerate/check the key in Fireflies Integrations.
GraphQL error: inspect JSON errors, especially code and extensions.helpUrls; do not retry malformed documents unchanged.
too_many_requests: honor retryAfter when present and reduce request rate.
Permission or plan restriction: audit events/rule executions can require Enterprise/admin access; AskFred mutations need AI credits. Escalate access, do not infer it.
Pagination: use transcript limit (50 or less) and skip; use documented cursors for audit/rule queries.
Webhook verification failure: compare the raw body, unmodified signature header, and the correct shared secret. Do not verify re-serialized JSON.
Safe escalation: capture the command (without credentials), exit code, response error code, and help URL; provide these to Fireflies support.