Errors

HTTP status codes, error codes and response shapes returned by the Kustomer API, what causes each, and which to retry.

The Kustomer API uses standard HTTP status codes. 2xx means success, 4xx means something about the request needs to change, and 5xx means something went wrong on Kustomer's side.

Error shape

Errors return an errors array of JSON:API error objects. Each has the HTTP status, a machine-readable code, a short title, and usually a detail and a source that names the parameter or points at the field that caused it:

401 Unauthorized
{
  "errors": [
    {
      "status": 401,
      "code": "unauthorized",
      "title": "Unauthorized",
      "detail": "org.permission.customer.read",
      "source": { "parameter": "roles" }
    }
  ]
}

Branch on status and code, and log title, detail and source. detail is for people: its wording can change. A few endpoints add meta, or a message field instead of detail, so read both:

Node.js
interface KustomerError {
  status?: number | string
  code?: string
  title?: string
  detail?: string
  message?: string
  source?: { pointer?: string; parameter?: string }
}

async function errorMessage(res: Response): Promise<string> {
  const body = await res.json().catch(() => null)
  const err: KustomerError | undefined = body?.errors?.[0]
  if (!err) return `HTTP ${res.status}`
  const where = err.source?.pointer ?? err.source?.parameter
  return [err.code, err.detail ?? err.message ?? err.title, where && `at ${where}`].filter(Boolean).join(': ')
}

Look up an error

InteractiveLook up an error

21 of 21 errors

  • 400badparamDon’t retry

    title: "Additional properties not allowed", "Missing required property: name" or a type error; source.pointer or source.parameter names the field

    Cause
    The body doesn’t match the operation’s request schema: an unknown or misspelled field, a missing required field, a wrong type, or an unknown enum value. Custom attributes need a valid type suffix, such as Str, Num or At.
    Fix
    Compare your body with the request schema on the operation’s reference page, starting at the field in source. If every field is reported, check you sent Content-Type: application/json.
  • 400SyntaxErrorDon’t retry

    title: "Unexpected token } in JSON at position 42"

    Cause
    The body isn’t valid JSON, usually a trailing comma, single quotes or an unescaped character from string concatenation.
    Fix
    Build the body with your language’s JSON encoder instead of string formatting.
  • 400invalidDon’t retry

    title: "Invalid Version", source.parameter: "version"

    Cause
    The version segment of the path, such as /v3/, isn’t one that resource supports.
    Fix
    Copy the path from the operation’s reference page. Most resources are /v1; some newer routes are /v2 or /v2.1.
  • 401unauthorizedDon’t retry

    title: "Unauthorized", source.parameter: "token"

    Cause
    No Authorization header, a header without the Bearer prefix, or a key that has expired, been deleted or belongs to a different org.
    Fix
    Send Authorization: Bearer <key>. Check the key with GET /v1/auth/tokens/current, and create a new one if it’s gone.
  • 401unauthorizedDon’t retry

    title: "Unauthorized", source.parameter: "ip"

    Cause
    The key has an IP allowlist, and the request came from outside it.
    Fix
    Call from an allowed address, or update the key’s CIDR ranges in Settings.
  • 401unauthorizedDon’t retry

    detail: "org.permission.customer.read", source.parameter: "roles"

    Cause
    The key is valid but doesn’t have a role the operation needs. detail lists the roles it accepts.
    Fix
    Add one of the roles in detail to the key, or use a key that has it. Each reference page lists the roles for that operation.
  • 401unauthorizedDon’t retry

    detail: "billing.subscription.<status>", source.parameter: "billing"

    Cause
    The org’s subscription isn’t active, so API access is suspended.
    Fix
    Ask an admin of the org to check its subscription.
  • 401unauthorizedDon’t retry

    title: "Unauthorized", source.parameter: "externalToken"

    Cause
    A chat login JWT was rejected: wrong secret, not HS256, no iat, or iat more than 15 minutes old.
    Fix
    Mint the token when the user signs in, sign it with the chat secret using HS256, and set iat in seconds.
  • 400badparamDon’t retry

    title: "Bad Param", source.parameter: "externalToken"

    Cause
    The chat login JWT verified, but its payload has neither email nor externalId.
    Fix
    Add externalId (your user ID) or email to the payload.
  • 403forbiddenDon’t retry

    detail: "Auth token associated with pod prod2 but request is being handled by prod1.", source.parameter: "pod"

    Cause
    The key belongs to an org in another region. On api.kustomerapp.com you get a 301 or 308 redirect instead.
    Fix
    Use your org host, https://<org>.api.kustomerapp.com, or the base URL for your org’s region.
  • 403forbiddenDon’t retry

    source.parameter: "billing", with a detail naming the feature, such as "AI Agents is not enabled for this org"

    Cause
    The org’s plan doesn’t include a feature the operation needs, such as AI Agents, AI Copilot or AI Summaries.
    Fix
    Ask an admin of the org to check which features its plan includes. The key and the request are fine.
  • 404notfoundDon’t retry

    title: "Not Found", source.parameter: "path"

    Cause
    No route matches the method and path: a typo, a wrong version segment, or the wrong HTTP method.
    Fix
    Copy the method and path from the operation’s reference page.
  • 404notfoundDon’t retry

    title: "Not Found", often with source.parameter: "id"

    Cause
    The record doesn’t exist, was deleted, or belongs to another org. Lookups such as externalId= return 404 when nothing matches.
    Fix
    For lookups, treat 404 as “not found” and create the record. Otherwise check the ID came from the same org.
  • 409conflictSometimes retry

    title: "Conflict"; detail such as "Optimistic Lock Conflict" (source.parameter: "rev") or a note that another write is in progress

    Cause
    Another write to the same record landed first, such as a concurrent update or a company hierarchy edge, or the change conflicts with the record’s current state.
    Fix
    If detail says a write was in progress, retry with backoff. Otherwise re-read the record and reapply your change.
  • 409duplicateDon’t retry

    title: "Duplicate", detail: "duplicate externalId", source.parameter: "externalId"

    Cause
    A unique value is already taken, such as a customer externalId or a klass name.
    Fix
    Look up the existing record by that value and update it instead of creating another.
  • 413PayloadTooLargeErrorDon’t retry

    title: "request entity too large" (some services return code request_entity_too_large)

    Cause
    The body is over the endpoint’s size limit. Limits depend on the endpoint; inbound webhooks and form hooks allow 400 KB.
    Fix
    Send less per request: split batches, and upload attachments separately instead of inlining them.
  • 414no JSON bodyDon’t retry

    An HTML or empty body, not JSON

    Cause
    The URL is too long, usually from too many IDs or filters in the query string.
    Fix
    Split the IDs into smaller batches, or use a search endpoint that takes the query in the body.
  • 422unprocessableDon’t retry

    title: "Unprocessable Entity" with a detail explaining the rule

    Cause
    The request is well formed but breaks a business rule, such as an invalid state transition.
    Fix
    Read detail and change the request. Repeating it unchanged gets the same answer.
  • 429too_many_requestsRetry

    detail: "too many requests", x-ratelimit-remaining: 0

    Cause
    Your API keys have used the org’s per-minute budget, or a person’s 1,000-per-minute limit. Search by API keys has its own 100-per-minute limit.
    Fix
    Wait until x-ratelimit-reset (epoch seconds) plus a little jitter, then retry. Watch x-ratelimit-remaining to slow down before you hit it.
  • 429too_many_requestsRetry

    x-ratelimit-object-remaining: 0 and x-ratelimit-object-reset

    Cause
    Too many changes to one record: 100 per 10 minutes for most objects, 600 per 10 minutes for a customer, or 120 new items per minute for one customer.
    Fix
    Wait until x-ratelimit-object-reset (epoch seconds), not x-ratelimit-reset, and batch changes to the same record instead of sending each one.
  • 5xxno JSON bodyRetry

    title: "unknown", or a 502, 503 or 504 with an HTML body

    Cause
    A temporary problem on Kustomer’s side, or a timeout between services.
    Fix
    Retry with exponential backoff. For POST, make the create safe to repeat first. If it keeps failing, contact support with the time and path.
Search by status (401, 4xx), code, a phrase from title or detail, or paste the whole response body.

Status codes

StatusCodeCommon causesRetry?
400badparamMissing required fields, wrong types, unknown enum values, unknown fields, bad custom attribute suffixNo: fix the request
400SyntaxErrorThe body isn't valid JSONNo: fix the request
401unauthorizedMissing Authorization header, missing Bearer prefix, expired or deleted key, request from outside the key's IP rangeNo: fix the credentials
401unauthorizedThe key is valid but lacks a role the operation needs. source.parameter is roles, and detail lists the roles that would work.No: use a key with the right role
403forbiddenThe key belongs to an org in another region, or your plan doesn't include the featureNo
404notfoundWrong ID or path, a lookup such as externalId= found nothing, or the record was deletedNo. For lookups, 404 is a normal "not found" answer.
409conflictA concurrent write to the same resource, such as a company hierarchy edge, or the record's state blocks the change, such as deleting a brand that's still in useSometimes: retry if the error says another write was in progress, or, for a brand delete, that the dependents couldn't be checked
409duplicateA unique value, such as a customer externalId, is already takenNo: look up the existing record
413PayloadTooLargeError, or request_entity_too_large from some endpointsThe body is over the endpoint's size limitNo: send less per request
414noneToo many IDs in a query stringNo: batch the IDs
422unprocessableThe request is valid but breaks a business ruleNo
429too_many_requestsOver the org-wide or an object rate limitYes, after x-ratelimit-object-reset for an object limit, otherwise after x-ratelimit-reset
5xxnoneA temporary problem on Kustomer's sideYes, with exponential backoff

Some services return their own codes, listed on their reference pages. When you don't recognize a code, fall back on the status.

Retry policy

Diagram source
flowchart TD
  R[Response] --> S{Status}
  S -- "2xx" --> OK[Done]
  S -- "429" --> W["Wait until x-ratelimit-object-reset<br/>or x-ratelimit-reset<br/>+ jitter, then retry"]
  S -- "5xx or network error" --> B["Exponential backoff<br/>0.5s, 1s, 2s, 4s… (max 5 tries)"]
  S -- "409 'in progress'" --> B
  S -- "other 4xx" --> F[Fail: log code and message, fix the request]

Retrying a POST that timed out can create duplicates. Make creates safe to repeat by setting externalId and looking it up before you retry. See Making requests.

Bulk job errors

Bulk jobs report errors per item instead of failing the whole request. When you send _clientRef, each result has a status of created, updated or error, and failed items include an error reason. See Bulk operations.

Debugging checklist

  1. Log the status, the errors array, the method and path. Never log the Authorization header.
  2. Reproduce the request with the Try it panel on the operation's reference page.
  3. Check the roles on the reference page against your key's roles from GET /v1/auth/tokens/current.
  4. For 400 errors, compare your body with the request schema on the reference page. Custom attribute names must end in a valid suffix.