Get started
Errors
The error document, status codes and what each one means.
The error document
Every 4XX and 5XX answer has the same JSON:API body: an errors array with one object per problem. Branch on status and code; the title and detail are written for people and can change.
{
"errors": [
{
"id": "1f0b6c5e-9a3d-4b6f-8f0e-2d7c4a1b9e53",
"status": 400,
"code": "invalid",
"title": "The request is not valid.",
"detail": "page[size] must be between 1 and 100.",
"source": {
"parameter": "page[size]"
},
"links": {},
"meta": {}
}
]
}| Field | What it holds |
|---|---|
id | The request id, also sent as the x-request-id header. Quote it when you ask us about a request. |
status | The HTTP status, as a number |
code | A stable machine-readable code |
title | A short summary of the kind of error |
detail | What was wrong with this request. It names fields, parameters and ids, never personal data. |
source | pointer to the bad value in the body (/data/attributes/email) or parameter naming the query parameter |
meta | Extra facts, such as duplicate_profile_id on a duplicate profile |
Status codes
| Status | Code | When |
|---|---|---|
| 200, 201 | Read or created. 201 answers a POST that created something. | |
| 202 | Accepted for work that finishes later | |
| 204 | Done, with no body (most deletes and relationship changes) | |
| 400 | invalid | A parameter, filter, sort, cursor or body value is not valid |
| 400 | invalid_revision | The revision header is missing or malformed |
| 401 | not_authenticated | No credentials were sent |
| 401 | authentication_failed | The key is wrong or revoked |
| 403 | permission_denied | The key or person lacks a scope the endpoint needs |
| 404 | not_found | No such resource, no such endpoint, an endpoint we have not built yet, or a revision we do not serve |
| 405 | method_not_allowed | The path exists but not with this method. The Allow header lists the methods. |
| 409 | duplicate_profile | Another profile already has this email, phone number or external id. meta.duplicate_profile_id names it. |
| 409 | conflict | The request conflicts with the resource's current state |
| 413 | payload_too_large | The body is larger than 5 MB |
| 415 | unsupported_media_type | The body is not application/json or application/vnd.api+json |
| 429 | throttled | Over a rate limit. See rate limits. |
| 500 | error | Something failed on our side. Retry with backoff. |
Endpoints that are not available yet
The API follows Klaviyo's list of endpoints, and some of them are still being built. Calling one of those answers 404 not_found with a detail that names the operation and says it is not available here yet, so a client gets a JSON error rather than an HTML page. The coverage table lists what is built.
Request bodies
Send bodies as application/vnd.api+json or application/json, up to 5 MB. When a body fails validation, the 400 names the first bad value with a JSON pointer in source.pointer.
Retrying
Retry 429 and 5XX answers with exponential backoff. Do not retry other 4XX answers unchanged: the same request will fail the same way.