Errors

Every failure has the same body shape. Branch on the code, not on the message — messages are written for people and may be reworded.

Error body

{
  "success": false,
  "message": "This API key does not have the UPDATE scope, which this endpoint requires.",
  "code": "open_network_scope_required",
  "details": {
    "requiredScope": "UPDATE",
    "grantedScopes": ["REGISTRATION", "INVENTORY"]
  },
  "requestId": "b7f1c2d4-9a03-4e11-bc55-2f8e6a91d730"
}

code and details appear only when the failure carries them; message, success and requestId are always present. Log the requestId — it is what lets Localoy find your exact request.

What each failure means

Returned by the endpoints your integration calls.

Status	Code	Meaning	What to do
400	—	A field failed validation. The message names the field and the rule it broke.	Fix the field. The rules are in the catalog item table above.
400	`external_id_immutable`	A PATCH body contained externalId.	Drop it from the body. To change an id, delete the item and create it under the new one.
401	`open_network_key_invalid`	The key was missing, malformed, unknown, wrong, revoked or expired. All six answer identically on purpose — telling them apart would let anyone probe which of your keys exist.	Call GET /ping with the same credential. If that also 401s, the key itself is the problem; re-read it from the portal or rotate it.
403	`open_network_scope_required`	The key is valid but lacks the scope this endpoint needs. details carries requiredScope and grantedScopes.	Edit the key on the Self-Managed page and tick the missing API. It takes effect on the very next request.
404	`open_network_item_not_found`	No item with that externalId belongs to this business. Another business's id looks the same as one that was never created.	Check the id, or create the item first with POST /catalog/items.
404	`open_network_bookable_not_found`	The localoyRef on the item names no bookable of this business — a mistyped id, or someone else's.	Take the id from GET /bookables with the same key.
409	`open_network_bookable_already_linked`	Another of your items is already linked to that bookable. details.externalId names it. One item answers for one bookable, or Localoy would not know whose stock to ask about.	Unlink the other item (localoyRef: null) first, or link this one to a different bookable.
429	—	The key exceeded its request allowance for the window.	Wait for the number of seconds in the Retry-After header, then continue.
500	—	Something failed on Localoy's side. The body carries a requestId and the failure is reported to our team automatically.	Retry with backoff. Quote the requestId if you open a support ticket.

Key management failures

Returned to this dashboard, not to your integration — but they are yours to resolve.

Status	Code	Meaning	What to do
409	`open_network_key_limit_reached`	A business may hold 20 active keys at once.	Revoke a key you no longer use. Revoked keys do not count towards the limit.
409	`open_network_key_revoked`	An edit, rotation or second revocation was attempted on a revoked key.	Revocation is final. Create a new key instead.
404	`open_network_key_not_found`	No key with that id belongs to your business.	Reload the key list — it may have been revoked from another session.