Errors

Every PickupBell error response has the same shape, regardless of status code:

{
  "error": {
    "code": "forbidden",
    "message": "missing scope: calls:read",
    "details": { "location_id": "…" }
  }
}

Error codes

`error.code`	HTTP	Meaning
`unauthorized`	401	Missing, malformed, or revoked Bearer token.
`forbidden`	403	Token is valid but lacks the required scope, or target belongs to another location.
`not_found`	404	The resource (or the location it belongs to) doesn’t exist from this caller’s perspective.
`validation`	400	Your request body or query parameter is wrong. `details` may include a field-level reason.
`conflict`	409	The operation would create a duplicate or break an invariant (e.g. removing the sole location owner).
`server`	500	Unhandled server-side error. Safe to retry with idempotency.

5xx responses are retry-safe — we return them specifically for transient conditions (database timeouts, upstream provider outages).
4xx responses are not retry-safe; fix the request and resubmit.
All POST endpoints are idempotent over the same payload: retrying the same POST /leads with the same body within a short window will not create duplicates.

MCP uses JSON-RPC 2.0 error codes, mapped from ServiceError:

JSON-RPC code	PickupBell `code`	Notes
-32600	(malformed request)	Raw JSON-RPC transport error
-32601	(method / tool not found)
-32602	`validation`
-32001	`unauthorized`	Missing / invalid Bearer token
-32002	`forbidden`	Scope missing
-32003	`not_found`
-32004	`conflict`
-32603	`server`

The error.data.httpStatus field on JSON-RPC errors carries the matching HTTP status for tools that round-trip through a REST proxy.