Errors

The adapter favors explicit, safe failure over silent guessing. This page covers the error responses you'll see and the failure modes you should handle.

HTTP responses

Webhook and push endpoints use status codes as a redelivery contract, not a rich error body:

The key principle: 200 does not always mean "applied." It can mean "acknowledged and dropped" for a payload that redelivery would never fix. Only transient problems return 500.

Unmapped items — dead-lettering

If a CanonicalOrder references an item or modifier with no mapping to your POS for its location, the order is not pushed. It raises ErrUnmappedItem and is dead-lettered for human attention — never retried, never sent with a guessed item.

Why: pushing a guessed item to a live kitchen is worse than not pushing at all. The fix is data (add the mapping), not a retry. See Core Concepts → Item mapping.

Duplicate orders — idempotency

Delivery is at-least-once. A redelivered orderPlaced or a resent create-order call must not produce a duplicate ticket:

• The inbound processor is idempotent on swoopOrderId.
• Your integration should use swoopOrderId as its POS idempotency key — pass it as your external/third-party reference. The POS returns 409 on a duplicate, which the integration treats as success (the order already exists).

Poison payloads

A webhook or push message the adapter cannot decode is logged and acked (200) so the upstream stops redelivering it. For status webhooks, returning an error from your WebhookTranslator is how you signal "poison — drop it." Reserve transient 500s for genuinely retryable conditions.

Failure & cancellation reasons

When you emit a failed or cancelled StatusEvent, populate reason so the member and club staff understand why (e.g. out of stock, kitchen closed). It is surfaced with the status change.