Errors

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

Most errors return an errors array. Each entry has a machine-readable code, a human-readable message, and optional meta:

400 Bad Request

{
  "errors": [
    {
      "code": "bad_request",
      "message": "Invalid request body or parameters.",
      "meta": {}
    }
  ]
}

Some endpoints return the JSON:API error object instead, with status, code, title, detail, source (pointing at the bad field) and meta. Write your error handling to accept both:

Node.js

interface KustomerError {
  code?: string
  message?: string
  title?: string
  detail?: string
  status?: 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.message ?? err.detail ?? err.title, where && `at ${where}`].filter(Boolean).join(': ')
}

Status codes

Status	Code	Common causes	Retry?
`400`	`bad_request`	Invalid JSON, missing required fields, wrong types, unknown enum values, bad custom attribute suffix	No: fix the request
`401`	`unauthorized`	Missing `Authorization` header, missing `Bearer` prefix, expired or deleted key, request from outside the key's IP range	No: fix the credentials
`403`	`forbidden`	The key is valid but lacks a role the operation needs	No: use a key with the right role
`404`	`not_found`	Wrong ID, a lookup such as `externalId=` found nothing, or the record was deleted	No. For lookups, `404` is a normal "not found" answer.
`409`	`conflict`	Duplicate unique value, or a concurrent write to the same resource, such as a company hierarchy edge	Sometimes: retry if the error says another write was in progress
`414`	`uri_too_long`	Too many IDs in a query string	No: batch the IDs
`422`	`unprocessable`	The request is valid but breaks a business rule	No
`429`	none	Over the org-wide or an object rate limit	Yes, after `x-ratelimit-reset`
`5xx`	none	A temporary problem on Kustomer's side	Yes, with exponential backoff

Retry policy

Diagram source

flowchart TD
  R[Response] --> S{Status}
  S -- "2xx" --> OK[Done]
  S -- "429" --> W["Wait until 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

Log the status, the errors array, the method and path. Never log the Authorization header.
Reproduce the request with the Try it panel on the operation's reference page, or with kusty api ... --dry-run to see exactly what would be sent.
Check the roles on the reference page against your key's roles from GET /v1/auth/tokens/current.
For 400 errors, compare your body with the request schema on the reference page. Custom attribute names must end in a valid suffix.