# Errors

{/* Generated by apps/docs/scripts/errors-page.ts from the spec snapshot. Edit ERROR_DOC in apps/api instead. */}

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 `{ path, message }`: `path` leads into the request body (`["images", 1]`, `["metadata", "responsibleId"]`), or is the parameter's name (`["id"]`) for a path or query parameter. Conflicts carry `reason`. Upload and geocoding errors have `message` only.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Stable machine-readable code, for example BAD_REQUEST. |
| `status` | integer | The HTTP status, repeated. |
| `message` | string | Human-readable; may change. |
| `data` | object | Present when there is something structured to say: `issues` on a validation error, `reason` on a conflict. |
| `data.issues` | array of object | What failed validation, one entry per problem. |
| `data.issues[].path` | array of string or integer | Where the problem is: keys and array indexes into the request body, like `["images", 1]` or `["metadata", "responsibleId"]`, or the parameter's name, like `["id"]`. Empty for the body as a whole. |
| `data.issues[].message` | string | Human-readable; may change. |
| `data.reason` | string | Why a `409` happened, stable and safe to branch on. Only `create_race` is worth retrying (once). |

The one exception is a request the hosting edge refuses before it reaches Shace, for example a URL with control characters (CR, LF, NUL) or a Unicode line separator (U+2028, U+2029) in it: that answer may not be JSON.

- `400 BAD_REQUEST`: field validation failed, an id is neither a UUID nor `ext:<reference>`, `cursor` is not a well-formed cursor (pass `nextCursor` back exactly as received), an image URL cannot be fetched (including a host name that does not resolve) or is not a supported image, a floor plan URL is not from your uploads, an image upload has more than 8 files, a floor-plan upload has more than one `file`, an uploaded file is over 15 MB or its content is not a supported format, an uploaded floor plan's content is a different format than its type or file name says (a PDF sent as `plan.png`) or is an image that does not decode, an address could not be geocoded, `contact` is missing (issue on `contact`) or cannot be assigned (issue on `contact.email` saying why), both `assignedTo` and `contact` were sent (issue on `assignedTo`), or a deal answer's `from` is not a member (issue on `from`).
- `401 UNAUTHORIZED`: missing, malformed, revoked or expired key.
- `403 FORBIDDEN`: the key's organization is not a landlord organization, or it called a Deals endpoint without full integration.
- `404 NOT_FOUND`: no listing, deal or webhook endpoint with that id (or listing reference) in your organization. Also returned for another organization's ids, so ids leak nothing.
- `405 METHOD_NOT_SUPPORTED`: the path exists but not with this method. The `Allow` header lists the methods it takes.
- `409 CONFLICT`: the resource is not in a state that allows this. `data.reason` says which, and only `create_race` is worth retrying:
  - `create_race`: two requests raced to create the same reference. Retry once.
  - `no_owner`: the organization has no owner yet to attribute listings to, or (on accepting a deal) to answer for it when the member the lead is routed to has left. Retrying does not help: the owner invite has to be accepted first, or send `from`.
  - `not_pending`: the deal was already answered, expired or withdrawn. A retried accept or decline whose first attempt timed out but went through gets this too, so after any `409` on accept or decline, `GET /deals/{id}` to see where the deal stands.
  - `tenant_not_ready`: the deal's tenant has not finished signing up. Try again later.
  - `listing_unpublished`: accepting a deal (or, in the sandbox, creating one) needs a published listing. Push it again first. Declining works either way.
  - `listing_not_yours`: the deal's listing no longer belongs to your organization.
  - Sandbox only: `not_accepted` (the step needs an accepted deal), `not_withdrawn` (only a withdrawn deal can come back), `contract_exists`, and `invalid_state` for any other step the deal is not ready for.
- `408 REQUEST_TIMEOUT`: an upload's body arrived too slowly. Shace allows 60 seconds plus the body's size at 256 KB per second from when it starts reading (about 9 minutes for a full image batch, 3 minutes for a floor plan). Retry, on a faster connection or with a smaller batch.
- `413 PAYLOAD_TOO_LARGE`: the whole request body is over the endpoint's cap, checked before any of it is read: 121 MB for image uploads (8 files of 15 MB), 31 MB for a floor-plan upload, 2 MB for any JSON body. A single file over 15 MB in a body under the cap is a `400`. Split the batch.
- `412 PRECONDITION_FAILED`: sandbox only, the sandbox's test tenant is not set up on this environment. Tell us; retrying does not help.
- `429 TOO_MANY_REQUESTS`: your organization went over a rate limit reported by `GET /me` (`requestsPerMinute` for every request, `uploadsPerMinute` for upload requests, however many files each carries), the organization already has an image upload (or two floor-plan uploads) in progress, or the organization sent more than 10 webhook test events in 10 minutes. Wait the number of seconds in the `Retry-After` header, then retry. The limits are fixed one-minute windows per organization, shared across its keys, so adding keys does not add capacity; responses to a valid key carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds) for the window closest to its limit.
- `503 IMAGE_HOST_UNAVAILABLE`: your image host did not answer, timed out, rate-limited Shace or answered a server error while Shace fetched an image URL on a listing. `data.issues` names the index. Retry with backoff. A host name that does not resolve at all is a `400`, and so is a push where any other image URL or file is invalid: retrying cannot succeed, so the `400` lists every failing index, the unavailable ones included.
- `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.

The API itself never answers `502` or `504`. One of those, with an HTML body instead of this shape, comes from the network in front of Shace: treat it like a `500`. The same goes for a `524`: the edge gives up on a very slow request, for example a push with many image URLs on slow hosts. Treat it like a `500`, and send fewer or smaller images per push.

**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` after `Retry-After`, `408`, `503` and `500` (and an edge `502`, `504` or `524`) with a short backoff, and a `409` whose `data.reason` is `create_race` once. Do not retry `400`; fix the body.
