Handle API errors - Bily developer docs

Bily returns standard HTTP status codes with JSON error bodies, so your application can choose the right recovery step.

{
  "error": "Store not found"
}

An unexpected server error can also include its request ID:

{
  "error": "Internal Server Error",
  "requestId": "2ae61752-6902-4d1b-a54a-b9843fbed75a"
}

Act on each status

Status	Meaning	Recommended handling
`400`	Invalid path, query, or request body	Fix the request. Do not retry unchanged.
`401`	Missing or invalid authentication	Replace or rotate the API key.
`403`	The identity or key lacks access	Verify key permissions and scope. Regenerate an older settings-generated key when the error requires a store scope.
`404`	The scoped resource was not found	Refresh customer context or resource IDs.
`409`	The request conflicts with current state	Read the resource and disambiguate or update the request.
`429`	Too many requests	Retry with exponential backoff and jitter.
`500`	Bily could not complete the request	Retry safe reads; investigate before retrying writes.
`502`	A dependent Bily operation was temporarily unavailable	Retry safe reads after a short delay.
`504`	The request did not complete before its timeout	Retry safe reads after a short delay or reduce the requested range.

Keep the request ID

Every response includes x-request-id. Record it with the operation and timestamp. You can send a safe correlation value in x-request-id or x-correlation-id. Bily returns the selected value as x-request-id.

const requestId = crypto.randomUUID();
const response = await fetch(
  "https://app.bily.ai/api/customer/v1/context",
  {
    headers: {
      "x-api-key": process.env.BILY_API_KEY!,
      "x-request-id": requestId,
    },
  },
);

if (!response.ok) {
  const bilyRequestId = response.headers.get("x-request-id");
  const body = await response.json().catch(() => null);
  throw new Error(
    `Bily request failed (${response.status}, request ${bilyRequestId}): ${JSON.stringify(body)}`,
  );
}

Keep customer data, credentials, and secrets out of request IDs.

Retry only when safe

Retry idempotent GET requests after transient 429, 500, 502, or 504 responses. Add jitter to capped exponential backoff. Do not automatically retry create, clone, update, toggle, delete, sync, or other mutation requests. First read the affected resource and confirm that the original write did not succeed.