> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bily.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle API errors

> Use status codes and request IDs to recover safely from Bily API failures.

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

```json theme={null}
{
  "error": "Store not found"
}
```

An unexpected server error can also include its request ID:

```json theme={null}
{
  "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`.

```typescript theme={null}
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.