Errors

The Brand Data API returns a small, well-defined set of HTTP statuses. Error responses carry a generic JSON body and never include internal details.

Error body

Authentication failures return:

{ "error": "Unauthorized" }

All other errors return a structured body with a machine-readable code and a human-readable message:

{
	"error": {
		"code": "conversation_not_found",
		"message": "Conversation not found"
	}
}

Status codes

`200 OK`

The request succeeded. List endpoints return a { data, nextCursor } envelope; single-resource endpoints return a { data } object. See each endpoint page for the exact shape.

`400 Bad Request`

Your request was malformed. Fix it before re-sending; do not retry unchanged.

On reads, the usual cause is an invalid cursor (code: invalid_cursor) — one that was not produced by a previous nextCursor.

On writes, code: bad_request covers a body that failed validation. The most common causes:

An unrecognised field. Write bodies are strict. A field we do not recognise is rejected rather than ignored, so a typo can never look like it worked.
An invalid event type. type must be a slug.
A payloadSchema that will not compile. It is checked with the same JSON Schema compiler that validates your inbound events, so a schema that saves is a schema that will validate.
Incomplete identifierMappings. You must supply external_id_path, plus at least one of email_path or phone_path — without a contact channel there is nobody for LiveRecover to reach, and the event would land and do nothing.

Authentication failed. Returned for a missing or malformed Authorization header, an unknown, revoked, or expired key, a key of the wrong kind, or a disabled integration. The body is always { "error": "Unauthorized" } and never reveals whether a key exists. See Authentication. Do not retry — correct the credentials first.

`403 Forbidden`

You authenticated, but the request is not allowed (code: forbidden).

The integration surface is not enabled for your brand. Contact your account contact.
You presented an API key to a /keys endpoint. Key management requires a dashboard session — an API key can never mint another API key.

`404 Not Found`

The requested resource does not exist or belongs to another brand. These two cases are deliberately indistinguishable: a conversation, contact, provider, or event definition owned by another brand returns the same 404 as an id that does not exist, so the API never confirms the existence of another brand's data.

A malformed id — anything that is not a UUID — is also a 404, not a 400.

Do not retry.

`409 Conflict`

The write collided with something that already exists, or with someone else's change (code: conflict). There are three ways to get one:

A duplicate provider key. A provider key is unique per brand. Note that if you omit key on create, we derive one from name and make it unique for you — you only get a 409 when you asked for a specific key that is already taken.
A duplicate event type. An event type is unique per provider.
A concurrent update. schemaVersion guards payloadSchema changes: if the definition changed underneath you between your read and your write, the update is rejected instead of silently overwriting. Re-read the definition and re-apply your change. This is deliberate — a lost update here would leave us validating your new events against a stale schema, silently.

`429 Too Many Requests`

You are at your provider limit (code: limit_exceeded). Each provider mints a credential, so the count is capped per brand. Remove or disable a provider you no longer use, or contact your account contact to raise the limit.

`5xx`

A transient error on our side. Retry with jittered exponential backoff. A 500 (code: internal_error) is an unexpected internal failure; a 502 (code: data_store_error) is an upstream data-store failure. Both carry only the generic { error: { code, message } } body — never any internal detail.

A failed read on our side always surfaces as a 5xx, never as an empty result or a 403. If we cannot answer, we say so rather than telling you there is nothing there.

Retry guidance

4xx — your request is wrong. Do not retry without changing it. The one exception is 409 from a schemaVersion conflict: re-read, re-apply, and send again.
5xx — transient. Retry with backoff.