Errors

The error body

Log detail. Show message and message_title to a person: they are written to be safe to display. field names the parameter at fault when one is. Quote request_id if you get in touch about it.

{
  "detail": {
    "error": {
      "code": "location_ambiguous",
      "field": "address",
      "detail": "3 candidates within 40m; none is a parcel centroid.",
      "message": "That address matches more than one parcel.",
      "message_title": "Which one did you mean?",
      "request_id": "req_01h455vb4pex5vsknk084sn02q"
    }
  }
}

Status codes

One is worth committing to memory: 404 means no such id, and nothing else. A location Placestack cannot answer for is not a 404.

401

No usable credential.

402

quota_exhausted: out of credit. Credit is prepaid and the balance cannot go below zero, so add credit rather than retrying.

403

entitlement_missing: the plan does not cover this operation.

404

No such id. The only meaning of 404.

422

The request cannot be answered as asked. The code says why.

429

rate_limited, with Retry-After.

501

not_available: this operation does not answer yet.

Error codes

Branch on code, never on the message. This list is read from the contract, and GET /vocabulary/error_code serves the authoritative one with the text that goes with each. The groupings below are editorial, to make 28 codes readable.

Responses that look like failures

Three of these return 200, so do not treat them as errors. A location too coarse for the grain you asked for carries resolution.state: insufficient_precision unless you pass strict=true, which makes it a 422. A row a filter cannot evaluate comes back marked indeterminate rather than dropped. And a jurisdiction with nothing behind it carries a coverage block saying so.

Filters, and what indeterminate means →