Errors

One error shape, a stable code for each failure, and what to do about it.

Every failure is { "error": { "code", "digest" } } with the HTTP status that means it. A 400 or 422 that names fields adds issues, each with the path into your request and a message to fix it from.

400 Bad Request

{
  "error": {
    "code": "invalid",
    "digest": "9f2c1b7a-5d40-4e8b-a1c3-6e7d0b2f4a95",
    "issues": [
      { "path": "price.max", "message": "must be between 10000 and 100000000 to buy" },
      { "path": "location.center", "message": "a search needs a place to start: a commute, a preferred area, or location.center" }
    ]
  }
}

Branch on `code`, never on the message, which is for a person and may be reworded. Codes are stable within v1.
Quote `digest` when you write to us. It is the request's id, the same as X-Request-Id, and it finds the request in our logs. A message never carries an exception or a stack.
A 4xx is yours to fix and fails the same way if sent again unchanged, except 429, which you retry after Retry-After.
A 5xx is ours. Retry with exponential backoff and jitter; for a start, keep the same Idempotency-Key. Quote the digest if it persists.
Unknown ids look the same as someone else's: 404 not-found. A malformed id is 404 too, so ids reveal nothing.
A path or method we do not have answers the same way: a path with no endpoint is 404 not-found, and a method an endpoint does not take is 405 method-not-allowed, with Allow naming the ones it does.

Every code

Every error code, status, meaning and fix: the same catalog as the table.

Field	Means
`code`	A short stable word. Branch on this, never on the message.
`digest`	The request's id. It finds the request in our logs; quote it when you write to us.
`issues`	Only on a 400 or 422 that names fields: each problem with its `path` into your request and a `message` to fix it from.
`detail`	Only on an engine door's 409 `not-claimable`: why the claim is not the caller's, as `{ reason }`.

Code	Status	What it means	What to do	Retry
`unauthenticated`	401	No credentialsThe request carried neither an API key nor a signed-in session.	Send `Authorization: Bearer <key>`.	No
`engine-unauthenticated`	401	Not the engineAn engine door was called without a Google ID token from the engine's own account for this tier's doors. We never say which part failed.	Only the cloud engine calls these doors. Mint the token for this tier's audience, from the engine's runtime account.	No
`invalid-api-key`	401	The key was not acceptedThe key is misspelled, expired, revoked, or its maker no longer administers the org. We never say which, so a probe learns nothing.	Check the key against Settings, then make a new one if it is gone.	No
`insufficient-scope`	403	The key lacks the scopeThe key is live but was not given the scope this endpoint needs. `WWW-Authenticate` names it.	Make a key with the scope, or change this key's access in Settings.	A person must act
`account-not-permitted`	403	This key cannot name an accountThe request sent `Livia-Account`, but the key was not given `account:associate`, or the Livia admin who made it no longer is one.	Use a key a Livia admin marked "Run for another account", or omit the header to act as the key's maker.	A person must act
`account-invalid`	400	Livia-Account is not an email or an idThe header was sent, but it is neither an email address nor a user id.	Send the realtor's email, or their user id.	No
`account-unknown`	404	No Livia account by that nameNo one with that email or id has signed in to Livia Match. The request does not create an account.	The realtor signs in once, then send that same email.	No
`forbidden`	403	Not allowed for this callerThe caller is not allowed to do this, such as a member calling an admin-only endpoint.	Ask an admin, or use a key made by one.	A person must act
`bad-origin`	403	Cross-origin writeA browser session tried to write from another origin. Servers calling with a key send no `Origin` and never see this.	Call from your server with a key.	No
`not-found`	404	Not foundNothing at that id in your workspace, or no endpoint at that path. A malformed id and someone else's id answer the same, so ids reveal nothing.	Check the path against this reference, then the id, and that the key belongs to the right person or org.	No
`method-not-allowed`	405	Method not allowedThe path is an endpoint, but not for this method. `Allow` names the methods it takes.	Send one of the methods `Allow` names.	No
`invalid`	400	The request failed validationA field is missing, mistyped or out of range. `issues` names every problem by its path.	Read `issues`, fix each path, send it again.	No
`invalid-json`	400	The body is not JSONThe body is empty where one is required, or is not valid JSON.	Send a JSON body with `Content-Type: application/json`.	No
`invalid-cursor`	400	The cursor is not one we issuedA `cursor` was edited, truncated, or came from a different list.	Pass back exactly the cursor a page linked to, or start again without one.	No
`invalid-idempotency-key`	400	Malformed Idempotency-KeyThe key is empty, too long, or has characters outside `A-Z a-z 0-9 . _ : -`.	Use 1 to 255 of those characters.	No
`invalid-if-match`	400	Malformed If-Match`If-Match` is not a revision number, quoted or not.	Send back the `ETag` a read returned.	No
`too-large`	413	The body is too largeThe body is over the endpoint's limit.	Send less. A search request is a few kilobytes.	No
`unsupported-type`	415	Unsupported content typeThe recording is not a type we transcribe, or its bytes are not the type its header claims.	Send audio/webm, audio/ogg or audio/mp4, with bytes of that type.	No
`unknown-client`	422	No such client`clientId` does not name a client in your workspace.	Use an id from your own clients, or send `null`.	No
`source-unavailable`	422	The source cannot be matched againstThe brief's `source` is not Homes for sale and not one of your workspace's active data sets, so a match could never run against it.	List what you can match against with `GET /api/v1/data-sets`, and use one of those `source` words.	No
`search-unrunnable`	422	The search cannot run as it isThe search has something its source cannot answer: a place Homes for sale cannot find, a commute or a rental against a data set, no source at all, or nothing a client asked for. A search that names no place is not refused: it looks around the org's market, or Nashville, TN. `issues` says which.	Change the search as `issues` says, then run it again.	No
`brief-unrunnable`	422	The brief cannot run as it isWhat the old `/matches` paths answer where a current path answers `search-unrunnable`: the search cannot run against its source as it stands. `issues` says why.	Change the search as `issues` says, then run it again.	No
`draft-empty`	422	Nothing to draft fromThe words named nothing a brief can use: no budget, rooms, place or feature. A brief of starting values would read as the client's, so none is made.	Add details such as a budget, bedrooms or a feature, and draft again.	No
`callback-url-refused`	422	The callback URL cannot be used hereThe `callbackUrl` is well formed but cannot be called back from this deployment: plain http to localhost works only on a development deployment.	Use an https URL your server answers on.	No
`callback-needs-key`	422	A callback needs an API keyA callback is signed with the secret of the key that started the run, and this run was started without one (a signed-in session).	Start the run with an API key that has a signing secret.	No
`no-signing-secret`	422	The key has no signing secretA callback is signed with the key's signing secret, and this key has none yet, so nothing it asked for could be signed.	Make a signing secret for the key in Settings, API keys, and keep it on your server; then start the run again.	A person must act
`unknown-home`	422	The run never had that homeA list of results or a share names a home that is not among the homes this run found, in the results or not.	Use the `id` of a home from this run: `results`, `removed` or `excluded` (`shortlist` on the old paths).	No
`rate-limited`	429	Too many requestsOver a rate: the key's requests a minute (the answer carries `RateLimit` headers), or an hourly cap on starting searches, drafting briefs, transcribing, or the share builder's AI.	Wait `Retry-After` seconds. Poll slower; a run changes about once a second at most.	After Retry-After
`monthly-cap-reached`	429	The key's monthly cap is spentThe key reached the requests-a-month cap its maker set. It refills on the first of the month, UTC.	Wait for `Retry-After`, or have an admin raise the cap in Settings.	A person must act
`too-many-active`	429	Too many runs in flightYou already have the most runs queued or running at once.	Wait for one to finish, or cancel one, then start again.	After Retry-After
`recently-emailed`	429	Emailed a moment agoA share is emailed to its client at most once every ten minutes.	Wait `Retry-After` seconds.	After Retry-After
`invite-cap-reached`	429	Invite cap reachedThe org sent its most invitations for the day, across Settings and the API.	Wait for `Retry-After`.	After Retry-After
`out-of-credits`	402	The org is out of runsThe org's runs for the month are spent.	An admin can raise the allowance.	A person must act
`person-limit-reached`	402	The person's limit is reachedThe person the key acts as has used their own monthly runs, though the org still has some.	An admin can raise this person's limit or move runs to them.	A person must act
`revision-mismatch`	412	The resource changed`If-Match` named a revision that is no longer current (a search's or a brief's), so nothing was written.	Read it again, merge, and send the new `ETag`.	A person must act
`idempotency-key-reused`	409	Idempotency-Key reusedThe key was already used for a different request.	Use a new key for a new request; reuse one only to retry the same request.	No
`id-unavailable`	409	That id is takenThe id you chose for a search, a client or a brief belongs to something that is not yours to replace.	Pick a new UUID.	No
`run-not-ready`	409	The run has no results yetThe run is still working, or was stopped or failed, so there are no results to arrange or to share.	Read the run until `status` is `complete`, then try again.	No
`match-not-ready`	409	The match has no shortlist yetWhat the old `/matches` paths answer where a current path answers `run-not-ready`: the run has no results yet.	Read the run until `status` is `complete`, then try again.	No
`client-has-no-access`	409	The client cannot sign in yetA shortlist can only be shared with a client who has access.	Give the client access with `POST /api/v1/clients/{clientId}/access`, then share.	No
`wrong-client`	409	Not the client this run was made forA run is shared with the client its search names. This client is not that one.	Attach the client to the search and run it again, or share with the search's own client.	No
`client-needs-email`	409	The client has no emailSomething needs to reach the client by email, and the client has none on file and none was sent.	Save an email on the client, or send one with the call.	No
`already-finished`	409	The run already finishedA finished run cannot be canceled, and an engine cannot post a different outcome for a run that already has its answer.	Read the run for its final state.	No
`not-claimable`	409	Not the engine's to claimThe run is finished, canceled, held by another attempt, out of claims, or a newer dispatch replaced this one. `error.detail.reason` says which.	Answer the task and stop: a duplicate is not a failure.	No
`lease-lost`	409	The lease is goneAnother attempt holds the run now, or the run moved on, so this attempt's events and outcome no longer land.	Stop this attempt.	No
`delivery-in-flight`	409	The callback is still being sentA delivery that is pending or sending is already on its way; only a delivered, stopped or dead one can be sent again.	Read the delivery until its `status` is final, then redeliver if you still need it.	No
`owner-protected`	409	The owner cannot be changedThe org's owner cannot be removed or have their role changed through the API. Ownership moves only in Settings, by the owner.	Change the owner in Settings.	No
`own-membership`	409	You cannot change your own membershipThe person the key acts as cannot remove themselves or change their own role.	Ask another admin.	No
`no-limit`	409	No limit to moveOne of the two people has no personal limit, so there is nothing to move between them.	Set a limit on that person first.	No
`over-room`	409	More than the giver has leftThe giving person has fewer unused matches this month than you asked to move.	Move fewer; `issues` says how many they have.	No
`pool-expired`	410	The pool is goneA run's pool of considered homes is kept 30 days after it finishes. The run keeps its result.	Read the run for its shortlist, or start a new match.	No
`studio-incomplete`	503	The AI settings are incompleteA prompt the match engine runs will not compose from Livia's AI settings, so the match was not started and nothing was spent. `issues` names the step.	Try again later, or tell us the digest.	With backoff
`search-unavailable`	503	Search is unavailableAn outside service a run needs is not configured here. `issues` names each.	Try again later, or tell us the digest.	With backoff
`not-configured`	503	Place lookup is unavailableNo place-lookup service is configured on this deployment.	Try again later.	With backoff
`places-failed`	502	Places are not answeringThe place-lookup provider failed, refused the request or did not answer in time. It is never answered as an empty list.	Try again.	With backoff
`email-failed`	502	The email could not be sentThe email provider refused the message or did not answer in time. The ten-minute wait is given back, so nothing was spent.	Try again.	With backoff
`transcription-unavailable`	503	Transcription is unavailableNo transcriber is configured on this deployment.	Try again later.	With backoff
`transcription-failed`	502	Transcription failedThe transcriber did not answer in time or refused the recording.	Try again.	With backoff
`ai-unavailable`	503	Livia cannot write hereNo model is configured on this deployment for drafting a brief or the share builder, or its studio prompt cannot be composed.	Try again later, or tell us the digest.	With backoff
`ai-failed`	502	The model failedEvery model call the request made failed or answered out of shape, so nothing was written or drafted.	Try again.	With backoff
`answer-screened`	422	The answer did not pass reviewLivia wrote an answer, but it did not pass the Fair Housing screen, so it was never sent.	Ask about the homes' features, prices or trade-offs.	No
`internal`	500	Something broke on our sideAn unexpected fault. Nothing about your request is wrong.	Retry with backoff and quote the `digest` if it persists.	With backoff

The two envelopes

Successes are { "data": ... } everywhere but one place. GET /api/v1/health answers a bare object with ok at the top level, because monitors expect it there, and an OpenAPI document answers itself. Every other answer, success or failure, is enveloped.

Header	What it does
`Deprecation`	On an old path only: when it became old, as `@` and a Unix time (RFC 9745). The path still answers exactly as it did; move to the one `Link` names.
`Link`	On an old path only: its successor (`rel="successor-version"`), with your own ids filled in, and the page that maps old words to new (`rel="deprecation"`).
`Authorization`	Your API key as a bearer token: `Bearer lmp_...`. Never put a key in a URL or a query string.
`Idempotency-Key`	Makes a retry safe. The same key with the same request replays the first answer and does no new work; the same key with a different request is refused with 409. 1 to 255 letters, digits and `. _ : -`.
`If-Match`	The `ETag` a read returned, for example `"3"`. A change is applied only if the search is still at that revision; otherwise the answer is 412 and nothing is written.
`ETag`	The search's revision, quoted. Send it back in `If-Match` to change or delete the search without overwriting someone else's change.
`Location`	Where to read the resource that was created or queued. Follow it; do not build the URL yourself.
`Retry-After`	Seconds to wait before asking again: on a run that is still working, and on every 429.
`Idempotent-Replayed`	`true` when this answer is the first one replayed for a repeated `Idempotency-Key`. Nothing new was started.
`RateLimit`	What is left of each of the key's limits and when it refills, in the structured syntax of draft-ietf-httpapi-ratelimit-headers-11: `"key";r=87;t=12`. On every answer to a call made with a key.
`RateLimit-Policy`	The key's limits: a quota `q` over a window of `w` seconds, for the minute (`"key"`) and, when the key has one, the month (`"month"`). For example `"key";q=120;w=60`.
`WWW-Authenticate`	On a 401 or 403 from a door that takes keys: the Bearer challenge (RFC 6750). A 403 names the scope the key lacked.
`X-Request-Id`	Optional on a request: a trace id of your own, 8 to 64 letters, digits and dashes, that we honor and echo on the response. An error body's `digest` carries the same value; quote it when you write to us.