Skip to content

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.

400 response
{
  "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": {}
    }
  ]
}
FieldWhat it holds
idThe request id, also sent as the x-request-id header. Quote it when you ask us about a request.
statusThe HTTP status, as a number
codeA stable machine-readable code
titleA short summary of the kind of error
detailWhat was wrong with this request. It names fields, parameters and ids, never personal data.
sourcepointer to the bad value in the body (/data/attributes/email) or parameter naming the query parameter
metaExtra facts, such as duplicate_profile_id on a duplicate profile

Status codes

StatusCodeWhen
200, 201Read or created. 201 answers a POST that created something.
202Accepted for work that finishes later
204Done, with no body (most deletes and relationship changes)
400invalidA parameter, filter, sort, cursor or body value is not valid
400invalid_revisionThe revision header is missing or malformed
401not_authenticatedNo credentials were sent
401authentication_failedThe key is wrong or revoked
403permission_deniedThe key or person lacks a scope the endpoint needs
404not_foundNo such resource, no such endpoint, an endpoint we have not built yet, or a revision we do not serve
405method_not_allowedThe path exists but not with this method. The Allow header lists the methods.
409duplicate_profileAnother profile already has this email, phone number or external id. meta.duplicate_profile_id names it.
409conflictThe request conflicts with the resource's current state
413payload_too_largeThe body is larger than 5 MB
415unsupported_media_typeThe body is not application/json or application/vnd.api+json
429throttledOver a rate limit. See rate limits.
500errorSomething 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.