Shace
Guides

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.

FieldTypeDescription
codestringStable machine-readable code, for example BAD_REQUEST.
statusintegerThe HTTP status, repeated.
messagestringHuman-readable; may change.
dataobjectPresent when there is something structured to say: issues on a validation error, reason on a conflict.
data.issuesarray of objectWhat failed validation, one entry per problem.
data.issues[].patharray of string or integerWhere 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[].messagestringHuman-readable; may change.
data.reasonstringWhy 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.

Last modified on