Errors

Every error code a Technology Provider can receive, what it means, and what to do about it.

Provider calls use the Open Network's error envelope: success: false, a message written for people, a stable machine-readable code, sometimes details, and a requestId. Branch on code, never on message.

Error envelope

{
  "success": false,
  "message": "This partner has paused your connection. Nothing can be done for them until they resume it.",
  "code": "connection_paused",
  "requestId": "3f0c9f8e-6a1d-4f5e-9b1a-2f1c0d9e7a41"
}

Keys and partner context#

Code	Status	Meaning	What to do
`open_network_key_invalid`	401	The key is missing, malformed, unknown, revoked or expired, or its secret is wrong.	Check the key. Do not retry.
`provider_suspended`	403	Localoy has suspended your company.	Stop, and contact your partnerships contact.
`provider_key_required`	403	A partner key called `/connections…` or `/webhooks…`.	Use a provider key.
`partner_id_required`	400	A partner-scoped call has no `X-Localoy-Partner-Id`, or it is empty.	Send the header.
`connection_not_found`	404	The partner is not connected to you: never connected, its code not yet claimed, or disconnected.	Stop acting for the partner.
`connection_paused`	403	The partner has paused you.	Hold its work until `connection.updated` with reason `resumed`.
`open_network_scope_required`	403	The connection's effective scopes lack the endpoint's scope. `details.requiredScope` names it; `details.grantedScopes` lists the effective scopes.	Ask the partner to grant the scope.

Connections#

Code	Status	Meaning	What to do
`connection_code_invalid`	404	The code is unknown, expired or already used, belongs to another provider, or its connection was disconnected.	Ask the partner for a new code.
`connection_claim_rate_limited`	429	More than 20 claims in 15 minutes with this key.	Wait for `Retry-After`.
`connection_not_found`	404	`GET /connections/{partnerId}` found no connection with that partner.	—

Acting for partners#

Code	Status	Meaning
`open_network_item_managed_elsewhere`	409	The `externalId` belongs to an item the partner or another integration manages. Use another `externalId`.
`open_network_item_not_found`	404	You have no item with that `externalId` for this partner. Items that others created answer the same.
`open_network_bookable_not_found`	404	`localoyRef` names a bookable that is not the partner's, or not in your modules.
`open_network_bookable_already_linked`	409	Another item is already linked to that bookable.
`payment_session_not_found`	404	The partner has no session with that ID in this key's environment, or its order is outside your modules.

The other catalogue and payment codes mean what they mean for a partner's key. See the Open Network API errors.

Webhooks#

Code	Status	Meaning
`webhook_endpoint_not_found`	404	No endpoint of yours has that ID.
`webhook_delivery_not_found`	404	No delivery of yours has that ID.
`webhook_endpoint_limit_reached`	409	You already have 10 endpoints. Delete one first.
`webhook_endpoint_duplicate`	409	You already have an endpoint with this URL in this environment. Change its events instead.
`webhook_endpoint_disabled`	409	A replay to a disabled endpoint. Enable the endpoint first.
`webhook_replay_connection_inactive`	409	A replay of a delivery about a partner whose connection is paused or has ended. A `connection.*` delivery can always be replayed.
`invalid_events`	400	`events` is not a non-empty list of known event names. `details.allowed` lists them.
`event_not_subscribable`	400	`events` includes `ping`, which every endpoint receives from its test anyway.
`environment_immutable`	400	A `PATCH` tried to change `environment`. Create an endpoint in the other environment instead.

Refused webhook URLs#

A URL that fails a check is refused with 400 and one of these codes:

Code	The URL
`not_a_url`	Is missing, or is not an absolute URL.
`too_long`	Is longer than 2,048 characters.
`protocol_not_allowed`	Does not use `http` or `https`.
`https_required`	Uses `http`. Use `https`.
`credentials_in_url`	Contains a username or password.
`fragment_not_allowed`	Contains a `#fragment`.
`port_not_allowed`	Uses a blocked port. See URL requirements.
`host_not_resolvable`	Has a host name that does not resolve.
`private_address`	Resolves to a private, loopback or link-local address.

Validation errors without a code#

Invalid input on a single field — a missing code in a claim body, an unknown environment, a limit out of range — is answered 400 with a message that names the field, and may carry no code. These are bugs in the calling code: log the message and fix the request.

Handling errors#

Status	Retry?
`400`, `401`, `404`	No. Fix the request, the key or the ID first.
`403`	No. A paused connection, a missing scope or a suspension needs someone else to act first.
`409`	Not as is. Read the current state, then decide.
`429`	Yes, after the `Retry-After` header's number of seconds.
`500`, `503`, network errors	Yes, with exponential backoff. A claim is safe to retry with the same code.