Schemas

Every error, on every route, has this one shape. `code` and `status` are stable and safe to branch on. `message` is for humans and may change. `data` is present when there is something structured to say; validation errors carry `issues` there, each with a `path` into the request body. - `400 BAD_REQUEST`: field validation failed, an id is neither a UUID nor `ext:<reference>`, a cursor is invalid, a media URL is not from your uploads, an amenity id is unknown, `assignedTo` is not a member, an address could not be geocoded, or a listing was pushed onto an archived object. - `401 UNAUTHORIZED`: missing, malformed, revoked or expired key. - `403 FORBIDDEN`: the key's organization is not a landlord organization. - `404 NOT_FOUND`: no listing or object with that id or reference in your organization. Also returned for another organization's ids, so ids leak nothing. - `409 CONFLICT`: two requests raced to create the same reference (safe to retry), or the organization has no owner yet to attribute listings to (retrying does not help: the owner invite has to be accepted first). - `413 PAYLOAD_TOO_LARGE`: the request body is larger than the endpoint allows: 8 files of 15 MB for image uploads, one 15 MB file for floor plans, 2 MB for any JSON body. Split the batch. - `429 TOO_MANY_REQUESTS`: reserved for the rate limit reported by `GET /me`. Not enforced yet, but build in a backoff that honours `Retry-After` so it keeps working when it is. - `500 INTERNAL_SERVER_ERROR`: something on our side, including a geocoding outage. Retry with backoff; if it persists, tell us the `X-Request-Id` response header. **Publish rules are not errors.** Missing images, a zero price or a missing notice period never produce an error. The listing is stored and the response lists them under `publishBlockers`. **Retrying.** `PUT` requests are idempotent by design: repeating one is safe and, when nothing changed, a no-op. Retry `429` and `500` with a short backoff, and a `409` from a create race once. Do not retry `400`; fix the body.