Debug booking failures — common issues and fixes

A booking times out when the venue agent does not respond to an A2A envelope within the configured TTL (default: 30 seconds). The consumer agent shows the guest a 'venue is not responding' message and offers to try again or pick an alternative.

Root causes: the venue agent's soul loader is slow (knowledge pack too large, embedding retrieval over 5 seconds), the 360Dialog webhook delivery is delayed (check delivery log), or the venue agent process crashed and the health check has not restarted it yet.

Fix: check Knowledge → Health for slow-retrieval warnings. If your knowledge pack has over 500 chunks, consider pruning old menu versions. Check Settings → Channels → Delivery Log for webhook latency. If latency exceeds 10 seconds consistently, open a support ticket with 360Dialog.

A2A bookings flow through ClawPulse, AGNT's inter-agent gateway. Envelope errors happen when the signed JSON envelope between the consumer agent and the venue agent fails validation. Common causes: expired signing key, mismatched venue_id in the envelope, or a schema version mismatch between sender and receiver.

Diagnose: go to Bookings → Failed and click the failed booking. The detail panel shows the raw A2A envelope, the validation error, and the ClawPulse trace ID. Search the trace ID in the ClawPulse dashboard to see exactly where the envelope was rejected.

Fix: if the signing key expired, the consumer agent's operator needs to rotate it (this is not a venue-side fix). If the venue_id is wrong, check that your venue's A2A registration is current under Settings → A2A → Registration. Schema mismatches resolve automatically when both sides update to the latest AGNT SDK.

A capacity conflict happens when two bookings compete for the same time slot and the venue's available capacity cannot accommodate both. AGNT uses optimistic locking on the slot table — the first booking to confirm wins, the second gets a 409 Conflict.

The guest whose booking was rejected sees a message like 'That time slot just filled up — here are three alternatives.' The alternatives come from the nearest available slots within a 2-hour window.

Fix: if you are seeing frequent capacity conflicts, your slot_duration_minutes or buffer_minutes may be too tight. Increase the buffer by 15 minutes and monitor for a week. If the issue is overbooking (two bookings confirmed for the same slot), that is a bug — export the booking log and open a support ticket immediately.

AGNT deduplicates bookings using a compound key of (guest_phone, venue_id, date, time_slot). If a guest sends 'book me a table for Friday 7pm' twice in thirty seconds (common when WhatsApp shows a single tick and they resend), the second request is silently dropped and the first booking proceeds normally.

Problems arise when the dedup window is too aggressive — if a guest genuinely wants two separate bookings on the same day (lunch and dinner), the second may be flagged as a duplicate. The venue admin shows duplicates under Bookings → Duplicates. You can manually release a flagged booking and confirm it.

Fix: if false-positive duplicates are frequent, adjust the dedup time window under Settings → Bookings → Dedup Window. The default is 60 seconds; increasing it to 120 seconds catches more true duplicates but may also catch more false positives. Find the right balance for your venue's booking pattern.

Webhook delivery failures mean AGNT sent a booking confirmation or update to your external system (POS, reservation platform, CRM) but the target did not respond with a 2xx status. AGNT retries with exponential backoff: 5 seconds, 30 seconds, 2 minutes, 10 minutes, 1 hour. After five failures the webhook is marked as dead and an alert fires.

Check Settings → Webhooks → Delivery Log for the HTTP status code and response body from the target. Common causes: the target URL changed, the target's SSL certificate expired, or the target is rate-limiting your requests.

Fix: update the URL if it changed. If the target is rate-limiting, reduce your webhook batch size under Settings → Webhooks → Batch Size. If the SSL cert expired, that is on the target's side — notify them and AGNT will retry automatically once the cert is valid.

When a booking failure cannot be resolved automatically, AGNT escalates. The escalation chain is: (1) venue admin inbox notification, (2) email to the venue's primary contact, (3) WhatsApp message to the venue's emergency number (if configured), (4) AGNT support ticket auto-created after 30 minutes with no human response.

Configure your escalation contacts under Settings → Escalation. Make sure the emergency WhatsApp number is a real human who can respond within 15 minutes during operating hours. A booking failure that sits in the inbox for an hour is a lost guest.

Pro tip: set up a Slack or Discord webhook under Settings → Integrations so booking failures appear in a channel your team monitors. The alert payload includes the guest name, requested time, failure reason, and a deep link to the booking detail panel.