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:
{
"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:
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
21 of 21 errors
Status codes
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
- Log the status, the
errorsarray, the method and path. Never log theAuthorizationheader. - Reproduce the request with the Try it panel on the operation's reference page.
- Check the roles on the reference page against your key's roles from
GET /v1/auth/tokens/current. - For
400errors, compare your body with the request schema on the reference page. Custom attribute names must end in a valid suffix.