Errors
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 norext:<reference>,cursoris not a well-formed cursor (passnextCursorback 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 onefile, 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 asplan.png) or is an image that does not decode, an address could not be geocoded,contactis missing (issue oncontact) or cannot be assigned (issue oncontact.emailsaying why), bothassignedToandcontactwere sent (issue onassignedTo), or a deal answer'sfromis not a member (issue onfrom).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. TheAllowheader lists the methods it takes.409 CONFLICT: the resource is not in a state that allows this.data.reasonsays which, and onlycreate_raceis 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 sendfrom.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 any409on 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, andinvalid_statefor 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 a400. 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 byGET /me(requestsPerMinutefor every request,uploadsPerMinutefor 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 theRetry-Afterheader, 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 carryRateLimit-Limit,RateLimit-RemainingandRateLimit-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.issuesnames the index. Retry with backoff. A host name that does not resolve at all is a400, and so is a push where any other image URL or file is invalid: retrying cannot succeed, so the400lists 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 theX-Request-Idresponse 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.