Graceful degradation

The sponsor path is opportunistic. Your product flow stays primary. When the API cannot or should not return a sponsored placement, the correct outcome is usually no-fill, not a broken app state.

Treat an unavailable placement as optional

A placement response can contain placement: null. Handle that result and request failures as an optional branch, then continue the primary product flow.

Fail soft around POST /v1/placements

placement-fallback.mjs

javascript

REST
const response = await fetch("https://api.wavebird.ai/v1/placements", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.WAVEBIRD_SECRET_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({    client_id: "wbproj_...",    session_id: "sess_...",    job_type: "chat",  }),});if (!response.ok) return null;const { placement } = await response.json();return placement ?? null;

No-fill is valid

No-fill is a normal runtime result. Treat it as a valid branch and keep the rest of the UI responsive.

Consent can block delivery

Missing or insufficient consent should prevent sponsor delivery without preventing the main product response.

Renderer must stay optional

Your UI should not depend on a successful sponsored placement. The slot can disappear, collapse, or render a safe fallback shell.

Need rollout review?

Start with the Server API. Use contact only when you need rollout review, enterprise coordination, or non-standard integration help.

Contact the team