klaviyo-incident-runbook

name	klaviyo-incident-runbook
description	Execute Klaviyo incident response procedures with triage, mitigation, and postmortem. Use when responding to Klaviyo-related outages, investigating API errors (401/403/429/5xx), or running post-incident reviews for Klaviyo integration failures on an on-call rotation. Trigger with phrases like "klaviyo incident", "klaviyo outage", "klaviyo down", "klaviyo on-call", "klaviyo emergency", "klaviyo broken".
allowed-tools	Read, Bash(curl:*), Bash(kubectl:*), Bash(npm:*)
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","klaviyo","email-marketing","cdp"]
compatibility	Designed for Claude Code

Klaviyo Incident Runbook

Overview

Rapid incident response for Klaviyo API outages and integration failures: quick triage, decision trees, mitigation steps, and postmortem templates. Use this skill to move from "Klaviyo is broken" to a classified severity, an applied mitigation, and a written postmortem — without improvising under pressure.

The heavy content (full triage script, per-error remediation blocks, and the communication + postmortem templates) lives in references/ so this file stays a fast high-level runbook you can follow end-to-end, then drill into for depth.

Prerequisites

• KLAVIYO_PRIVATE_KEY exported in the shell (a private API key, pk_...).
• curl and python3 available for the triage and monitoring commands.
• Read access to your app's health endpoint and, ideally, its Prometheus metrics.
• Access to the Klaviyo dashboard to rotate a key if needed.
• Klaviyo's revision header value your app ships (this runbook pins 2024-10-15, a dated stable API version — Klaviyo requires the header on every request).

Severity Levels

Level	Definition	Response Time	Example
P1	Complete outage	<15 min	All Klaviyo API calls returning 5xx
P2	Degraded service	<1 hour	429 rate limiting, high latency
P3	Minor impact	<4 hours	Webhook delays, single endpoint errors
P4	No user impact	Next business day	Monitoring gaps, deprecation warnings

Instructions

Work the incident in five steps. Each step points at the reference file that carries the full, copy-paste-ready detail.

1. Triage immediately. Run the quick-triage script to answer the four questions that classify every Klaviyo incident: Is Klaviyo itself down? Can we authenticate? Are we rate limited? Is our app healthy? See the full script in references/triage.md.
2. Classify the failure. Walk the decision tree in references/triage.md to split a Klaviyo-side outage (status page shows an incident → enable fallback, monitor, communicate) from an integration issue (route by status code: 401/403, 429, 400, 5xx).