Przejdź do treści
Biblioteka skilli
Programowanie · Analiza

klaviyo-common-errors

/klaviyo-common-errors

Diagnozuje i naprawia typowe błędy API Klaviyo, w tym błędy 4xx i 5xx, nieudane żądania i problemy z integracją SDK.

Licencja
MIT
Ostatnia zmiana repozytorium
26.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
4
Przestarzałość

Brak sygnałów. Repozytorium zmienione 26.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Diagnozuje i naprawia typowe błędy API Klaviyo, w tym błędy 4xx i 5xx, nieudane żądania i problemy z integracją SDK.

Wyzwalacze z opisu

klaviyo errorfix klaviyoklaviyo not workingdebug klaviyoklaviyo 400klaviyo 429
Oryginalny opis (EN)

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".

Jak działa

  1. Overview
  2. Prerequisites
  3. Instructions
  4. Output
  5. Error Handling
  6. Examples
  7. Resources
Sekcje z nagłówków SKILL.md, w oryginale · 124 linii, 777 słów
Podgląd SKILL.md
---
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 <jeremy@intentsolutions.io>
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:

```typescript
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.

### Step 2: Match and Fix

Map the status code to its root cause and remedy. Each row links into the full
catalog, which carries the actual response payload and the fix code block:

| Status | Meaning | Most common root cause |
|--------|---------|------------------------|
| 400 | Bad Request | Missing field, non-E.164 phone, or `snake_case` instead of `camelCase` |
| 401 | Unauthorized | Missing `KLAVIYO_PRIVATE_KEY`, or a public key used as a private key |
| 403 | Forbidden | API key lacks the required scope (e.g. `profiles:write`) |
| 404 | Not Found | Wrong resource ID or a dead `/api/v2/` path |
| 409 | Conflict | Duplicate — use `createOrUpdateProfile` upsert |
| 429 | Rate Limited | Exceeded burst (75/s) or steady (700/min); honor `Retry-After` |
| 500/503 | Server Error | Klaviyo-side — check status page, retry with backoff |

The most common one, 400, is almost always a casing mismatch (the SDK expects
`camelCase`):

```typescript
// Wrong: snake_case              // Right: camelCase (SDK convention)
{ first_name: 'Jane' }            { firstName: 'Jane' }
```

See [the full error catalog](references/error-catalog.md) for every status
code's real payload, complete cause list, and fix. For client-side failures that
never reach the network (wrong import, `response.data` vs `response.body.data`,
bad filter syntax) plus copy-paste diagnostic commands, see
[diagnostics & SDK errors](references/diagnostics.md).

## Output

Working through this skill produces a diagnosis and a fix, not a generated
artifact:

- The **status code** and **error `code`** identifying the failure class
- The **root cause** matched from the catalog
- A **concrete code or config change** (casing fix, scope grant, upsert, backoff)
- For 5xx: confirmation of whether the fault is Klaviyo-side (status page) or yours

## Error Handling

- **Status code is missing from the exception** — the failure is client-side, not
  an API response. Check the SDK-level errors table in
  [diagnostics](references/diagnostics.md) (module-not-found, wrong constructor).
- **401 persists after setting the key** — you are using a public key. Verify with
  `echo $KLAVIYO_PRIVATE_KEY | head -c 3` (must print `pk_`).
- **429 with no `RateLimit-Remaining` header** — expected. On a 429 Klaviyo returns
  only `Retry-After`; do not depend on the reset headers, honor `Retry-After`.
- **Fix does not resolve the error** — collect evidence with `klaviyo-debug-bundle`,
  check [status.klaviyo.com](https://status.klaviyo.com), then open a support
  ticket with the request IDs from the error responses.

## Examples

**Example — 403 permission_denied on profile create.** The exception shows
`status: 403`, `detail: "...required scope: profiles:write"`. Match to the 403 row:
the key lacks a scope. Fix: mint a new key with `profiles:write` at
**Settings > API Keys**. Full payload and the endpoint→scope table are in
[the error catalog](references/error-catalog.md) under the 403 section.

**Example — intermittent 429 under load.** Requests fail once traffic exceeds
700/min. Honor the `Retry-After` header and back off instead of tight-retrying:

```typescript
if (error.status === 429) {
  const retryAfter = parseInt(error.headers?.['retry-after'] || '10'); // seconds
  await new Promise(r => setTimeout(r, retryAfter * 1000));
  // then retry
}
```

More worked cases (400 casing, 404 stale ID, 409 upsert) are in
[the error catalog](references/error-catalog.md).

## Resources

- [Full error catalog](references/error-catalog.md) — per-status-code payloads and fixes
- [Diagnostics & SDK errors](references/diagnostics.md) — client-side failures, diagnostic commands, escalation
- [Rate Limits & Error Handling](https://developers.klaviyo.com/en/docs/rate_limits_and_error_handling)
- [API Error Alerts](https://developers.klaviyo.com/en/docs/review_api_error_alerts)
- [Klaviyo Status Page](https://status.klaviyo.com)
- For evidence collection see the `klaviyo-debug-bundle` skill
Pliki w paczce (3)
  • SKILL.md 6 KB
  • references/diagnostics.md 1 KB
  • references/error-catalog.md 4 KB

Wersje

W bazie nie ma innych skilli o nazwie klaviyo-common-errors.

Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.

Migawka bazy z 13.11.2026 · wersja paczki 2a6b11671847 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100hex-common-errors
    Diagnozuje i naprawia typowe błędy oraz wyjątki Hex, w tym nieudane żądania i problemy z integracją.
  • 100exa-common-errors
    Diagnozuje i naprawia typowe błędy i wyjątki Exa, w tym nieudane żądania i problemy z integracją.
  • 100firecrawl-common-errors
    Diagnozuje i naprawia typowe błędy i wyjątki FireCrawl oraz nieudane żądania i problemy z integracją.
  • 100framer-common-errors
    Diagnozuje i naprawia typowe błędy i wyjątki Framer, w tym nieudane żądania i problemy z integracją.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.