Errors

Every error is JSON with an error code and an error_description. Branch on the code — the description is written for a person and may change.

{
  "error": "validation",
  "error_description": "scope is required and must be one of: primary_only, primary_and_garage, all_structures"
}

Match codes case-sensitively, and expect both casings. Lower-case codes come from the request layer; upper-case ones are raised deeper, in ordering and revisions. validation and VALIDATION are two distinct codes that both mean "a field is missing or malformed" — a check for one will not catch the other.

Code	HTTP	Meaning
unauthorized	401	Missing, invalid, or revoked key
validation	400	A field is missing or malformed
not_found	404	No such order on this account. Also returned for an order belonging to someone else, and for a beta endpoint that is not enabled on this account
server_error	500	Something went wrong on our end. Retry

Code	HTTP	Meaning
VALIDATION	400	Address or coordinates missing once the request layer has handed off
INSUFFICIENT_CREDITS	402	Available balance won't cover the report (and its ESX, if the order includes one)
BRAND_NOT_FOUND	400	brand isn't one of this account's brand profiles (a typo, or another account's id). Nothing was placed
ESX_NOT_SUPPORTED	400	"esx": true on a report type that has no ESX (Rapid Squares). Nothing was placed; leave esx out or send false
BILLING_SETUP_REQUIRED	402	No card or balance on the account yet
BRAND_NOT_FOUND	400	brand isn't one of this account's brand profiles (a typo, or another account's id). Nothing was placed or charged
PRODUCT_NOT_ENABLED	403	A product that isn't turned on for this account. Nothing was charged
ORDER_IN_PROGRESS	409	An order with this Idempotency-Key is still being placed. Retry in a few seconds
ENV_MISMATCH	400	The key's environment and the order's don't agree. Should be unreachable
BILLING_NOT_CONFIGURED	503	Billing isn't available on our side. Not your account — retry or contact support
ORDER_FAILED	502	The order was refused at placement. Not about the address — a property that can't be measured is only ever discovered on review and arrives later as a cancelled webhook. This is something our end; nothing was charged, and it's worth reporting. Also returned when retrying an Idempotency-Key whose first attempt failed: use a new key

Code	HTTP	Meaning
validation	400	A field is missing or malformed (a date of loss in the future, an unknown template)
needs_date_of_loss	400	The Date of Loss PDF was asked for without a date. Pass dateOfLoss
INSUFFICIENT_CREDITS	402	Less than $5 available. Nothing was looked up or charged
BILLING_SETUP_REQUIRED	402	Add a card and top up first
NOT_REVISABLE	400	Storm reports aren't revised: read them with new details, or order again
service_unavailable	503	Weather data didn't answer in time. No order was created and nothing was charged; retry

Code	HTTP	Meaning
INSUFFICIENT_CREDITS	402	Available balance won't cover the ESX. Nothing was charged
BILLING_SETUP_REQUIRED	402	No card or balance on the account yet
not_found	404	No such order on this account
NOT_UPGRADABLE	409	The order was cancelled, so there's no report to add ESX to
ESX_NOT_SUPPORTED	409	A Rapid Squares order: it never has an ESX

Code	HTTP	Meaning
VALIDATION	400	topic or notes missing or blank
INVALID_TOPIC	400	Topic isn't one of the accepted values
NOT_REVISABLE	409	Revisions need a delivered report — this order isn't completed
REVISION_ALREADY_OPEN	409	One open revision per report
CLAIM_NOT_FOUND	409	The report couldn't be matched for revision. Contact support with the order id
REVISION_REJECTED	409 (or 4xx / 502)	The revision was refused. The description says why
REVISION_FAILED	502	The revision couldn't be raised. Safe to retry
NO_CLAIM	500	The order is missing what a revision needs. Contact support with the order id

Code	HTTP	Meaning
ESX_NOT_PURCHASED	403	The order doesn't include ESX. The message names POST /api/v1/reports/orders/:id/esx and what it costs; price and currency in the body carry it
ESX_NOT_SUPPORTED	404	A Rapid Squares order has no ESX
not_ready	409	Report hasn't completed, so the file doesn't exist yet. Carries the current status
not_available	404	That file doesn't exist for this kind of report: a Rapid Squares order has no diagrams, and only Rapid Squares has a /photo
no_geometry	409	That structure has nothing drawable. Delivered, but there is no sketch to render
download_failed	502	ESX download failed. Safe to retry — nothing was charged
render_failed	500	The PDF or diagram couldn't be drawn

Code	HTTP	Meaning
validation	400	companyName is missing, an email isn't valid, a colour isn't hex, or text is over its limit
not_found	404	No such profile on this account. Also what a PDF link with an unknown or foreign ?brand= returns, on an order placed before 22 October 2026
profile_limit	409	The account already has 500 profiles
BRAND_IN_USE	409	Deleting a profile that orders were placed for: their reports keep that brand, so it stays. Edit it instead
BRAND_IN_USE	409	Orders were placed for this profile, so it can't be deleted. Edit it instead
empty_upload	400	The logo body was empty
too_large	413	The logo is over 5MB
payload_too_large	413	The request body is over 6MB
unsupported_type	415	The logo isn't a PNG, JPEG, WebP, GIF, AVIF or SVG
unreadable_image	422	The file couldn't be read as an image