Errors

Every error has the same shape:

{ "error": { "code": "allowance_exhausted", "message": "This month's 2,000 visits have been used. Upgrade your plan to continue.", "details": { "upgradeUrl": "/admin/usage" } } }

Branch on code; message is for people and may change. details appears where there's more to say. For validation_failed, it lists each problem field.

Status	Code	When
400	validation_failed	The body or query doesn't match the schema; see details.
400	duplicate_visit	A visit appears in two dispatch lanes.
401	unauthorised	Missing, unknown or revoked API key.
402	allowance_exhausted	This month's visits are used up.
402	operative_limit	The plan's active operatives are full.
402	feature_not_in_plan	For example, route history without visit history.
402	address_lookup_limit	This month's typed-address lookups are used up (postcodes and UPRNs still work).
403	email_unverified, not_eligible	The organisation can't create visits yet.
403	user_required	Only a signed-in person can do this, for example manage API keys.
404	not_found	It doesn't exist, or belongs to another organisation.
409	invalid_state	The visit isn't in a state that allows this, such as positions after arrival.
413 / 415	photo_too_large / photo_type	Operative photos: under 1 MB, JPEG, PNG or WebP.
422	unknown_operative	operativeId isn't one of your operatives.
422	uprn_not_found	The UPRN isn't in OS Open UPRN.
422	address_search_off	Typed addresses can't be searched; use a postcode or UPRN.
429	locked	Too many failed sign-ins; try again later.