Errors

One shape, always:

{
  "error": {
    "code": "invalid_field",
    "message": "City is required",
    "field": "loss_city"
  }
}

code is for your code, message is for a human reading a log, and field appears when one field is at fault.

Status codes

Status	Meaning	What to do
`200`	Fine
`201`	Created
`401`	Key missing, invalid, expired, or not an organisation key	Check the header; issue a new key
`403`	The key lacks the scope for this call	Add the scope, or use another key
`404`	No such request or home for your organisation	Check the reference
`405`	Wrong method for that path
`413`	The file is too large	Send under 10 MB
`429`	Over the rate limit	Wait for `Retry-After` seconds
`409`	The call does not fit the current state	e.g. setting dates before adding the home
`422`	A field is missing or wrong	Fix the named field
`400`	The body could not be read, or the write was refused
`500`	Our fault	Retry; if it persists, tell us the time and reference

Codes you will meet

`code`	Meaning
`missing_key`	No `Authorization` or `x-api-key` header
`invalid_key`	Not a valid organisation key
`forbidden`	The key does not carry the scope this call needs
`invalid_field`	Named field missing or invalid
`invalid_json`	The body was not JSON
`not_found`	No such request or home for your organisation
`not_on_request`	That home is not on the request yet
`budget_not_approved`	Approve the home’s budget before sending or placing it
`could_not_create`	The request could not be written
`could_not_place`	The home could not be placed
`could_not_set_dates`	The dates could not be set
`stay_too_short`	The dates span under 30 days
`dates_unavailable`	Something already holds part of that range
`already_signed`	The lease is fully signed — cancel rather than re-date
`already_paid`	Money has settled on that placement — refund before cancelling
`nothing_to_refund`	No settled payment on that home
`refund_pending`	A refund request is already with the landlord
`no_such_adjuster`	That address is not an adjuster on Havnly
`no_billing_account`	Your organisation is not linked to a carrier billing account
`could_not_read`	A read was refused — the message says why
`unsupported_type`	That file type is not accepted
`file_too_large`	Over the 10 MB limit for a document
`not_yours`	That document was not uploaded through your integration
`no_coordinator`	Nobody is assigned to source for this request yet
`idempotency_key_reused`	That key was already used for a different body
`request_in_progress`	The first call with that key is still running
`idempotency_key_too_long`	Keys are at most 255 characters
`rate_limited`	Over the per-minute limit — see `Retry-After`
`no_endpoint`	Nowhere to replay that event to
`sandbox_only`	That call is only available to sandbox keys
`unknown_event`	Not an event we send — check the spelling
`could_not_replay`	The replay could not be queued
`server_error`	Our fault

Retrying

500 and network failures are worth retrying with backoff. 4xx will not change on a retry — fix the call.

Always send external_id on POST /claims. A retry then returns the request you already created instead of opening a second one for the same household.

OpenAPI spec Going live