Errors

Every error has the same shape:

{
  "error": {
    "type": "invalid_attributes",
    "message": "Some attributes could not be stored.",
    "details": [{ "key": "exam_year", "message": "expected a number" }]
  }
}

type is a stable machine name. Branch on it. message is one sentence for a human reader, and it can change. details is present when Kai can name the attributes or the identities that caused the error.

Status codes

Code	Meaning
200	The request succeeded.
201	A record was created.
400	Kai could not read the request.
401	The API key is missing or not valid.
403	The key lacks the permission that this endpoint needs.
404	There is no such record in this workspace.
409	The write conflicts with a record that exists.
422	Kai read the request but could not store an attribute.

The batch endpoint returns 200 whenever Kai understands the request, even when every operation in it failed. Read summary.errors and the results array.

Error types

`unauthorized` (401)

The key is missing, unknown, revoked or expired. The message is the same for all four, so a caller cannot learn which key ids exist. Make sure that the header is Authorization: Bearer kai_live_.... Then make sure that the key is not revoked, in Settings → API.

`forbidden` (403)

The key is valid but lacks a permission. The message names the permission. Create a key with that permission, in Settings → API.

`invalid_request` (400)

The body or a query parameter is wrong. The message says which one. Common causes:

the request carries no identity, so Kai has nothing to match on;
a field holds the wrong JSON type;
an owner value that no member of the workspace holds;
a cursor value that Kai did not issue.

`identity_conflict` (409)

The identities in the request belong to two different contacts. Kai does not merge contacts. details names the identities. Correct the conflict in Kai, under Contacts, or write to each contact by its Kai id. See Identity.

`invalid_attributes` (422)

One or more attributes could not be stored. details names each key and the reason:

Reason	What to do
`no such workspace attribute`	Create the attribute with `POST /attributes`.
`this workspace attribute is archived`	Restore it with `DELETE /attributes/{key}?restore=true`.
`expected a number`	Send a number, or a string that holds one.
`expected one of: ...`	Send one of the options of the `select` attribute.
`expected a date as YYYY-MM-DD`	Send a calendar day, not a timestamp.

Kai stores none of the attributes in a request that holds a bad one. Correct the value and send the request again.

`type_conflict` (409)

POST /attributes names a key that exists and stores a different type. The type of an attribute cannot change. Archive the attribute and create another one with a new API name.

`too_many_operations` (400)

A batch holds more than 1000 operations. The message says how many requests to send. See Import many contacts.

`not_found` (404)

There is no record with this id in the workspace of the key. A key reaches one workspace only, so an id from another workspace answers 404 and not 403.

Retries

A 500 response and a network timeout can be retried. All write endpoints match on identity, so a repeated request updates the same contact and does not make a copy. Do not retry a 400, a 403, a 409 or a 422. The same request fails the same way. Correct the request first.

Start here

Concepts

How to

Status codes

Error types

`unauthorized` (401)

`forbidden` (403)

`invalid_request` (400)

`identity_conflict` (409)

`invalid_attributes` (422)

`type_conflict` (409)

`too_many_operations` (400)

`not_found` (404)

Retries

​Status codes

​Error types

​unauthorized (401)

​forbidden (403)

​invalid_request (400)

​identity_conflict (409)

​invalid_attributes (422)

​type_conflict (409)

​too_many_operations (400)

​not_found (404)

​Retries

Status codes

Error types

`unauthorized` (401)

`forbidden` (403)

`invalid_request` (400)

`identity_conflict` (409)

`invalid_attributes` (422)

`type_conflict` (409)

`too_many_operations` (400)

`not_found` (404)

Retries