klaviyo-common-errors

name	klaviyo-common-errors
description	Diagnose and fix common Klaviyo API errors and exceptions. Use when encountering Klaviyo 4xx/5xx errors, debugging failed requests, or troubleshooting SDK integration issues. Trigger with phrases like "klaviyo error", "fix klaviyo", "klaviyo not working", "debug klaviyo", "klaviyo 400", "klaviyo 429".
allowed-tools	Read, Grep, Bash(curl:*), 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 Common Errors

Overview

Quick reference for the most common Klaviyo API errors with real error payloads, root causes, and solutions. Because Klaviyo returns JSON:API errors (a status code plus a structured errors[] array), this skill walks you from a raw exception to a targeted fix: extract the status code, match it against the catalog, apply the documented remedy.

The full per-status-code catalog and the SDK-level failure table live in references/ to keep this workflow scannable — drill in once you know which status code you are chasing.

Prerequisites

• klaviyo-api SDK installed (npm install klaviyo-api — note: not @klaviyo/sdk)
• A private API key (pk_*) exported as KLAVIYO_PRIVATE_KEY
• Access to the application logs where the failed request was recorded, so you can Read the stack trace and Grep for the status code and error code

Instructions

Step 1: Identify the Error

Extract the status code and error detail from the caught exception. Read the log line or wrap the call so the structured payload is visible:

try {
  await profilesApi.createProfile(payload);
} catch (error: any) {
  console.error('Status:', error.status);
  console.error('Errors:', JSON.stringify(error.body?.errors, null, 2));
  // error.body.errors[] has: { id, code, title, detail, source }
}

If you only have raw logs, Grep for the status code (grep -E "40[0-9]|429|50[0-9]") and the code field to isolate the failing request.