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

# Error Handling

> How the gateway manages and communicates failures

The LLM Gateway is designed to be resilient, ensuring that even if a backend or LLM provider fails, the conversation can continue gracefully.

## Standard Error Codes

The gateway standardizes errors into a set of machine-readable codes:

| Code                  | Status | Description                                           |
| --------------------- | ------ | ----------------------------------------------------- |
| `auth_required`       | 401    | API key or session is missing/invalid.                |
| `rate_limit_exceeded` | 429    | Too many requests for this account or session.        |
| `backend_timeout`     | 504    | Your commerce platform didn't respond in time.        |
| `product_not_found`   | 404    | The requested ID does not exist in the catalog.       |
| `invalid_arguments`   | 400    | The LLM passed arguments that don't match the schema. |

## Informing the LLM

When an error occurs during a tool call, the gateway doesn't just crash. It returns an error object to the LLM that explains what went wrong, often with "hints" on how the AI can recover.

**Example Error Response to LLM:**

```json theme={null}
{
  "error": "product_not_found",
  "message": "Product 'sku-123' is no longer in the catalog.",
  "hint": "Try searching again with keywords like 'running shoes' to find a similar item."
}
```

This allows the AI to say: *"I'm sorry, I couldn't find those specific shoes anymore. Should I look for a similar pair of running shoes for you?"*

## Circuit Breakers

In the [Marketplace](/hosted/marketplace) tier, the gateway includes automatic circuit breakers. If a specific merchant's API is consistently failing, the gateway will temporarily disable their tools to prevent slowing down the entire network.

## Client-Side Handling

When using the HTTP Adapter, you should check for a non-200 status code and handle the standard error JSON:

```typescript theme={null}
const response = await fetch(gatewayUrl, ...);
if (!response.ok) {
  const err = await response.json();
  console.error(`Gateway Error [${err.code}]: ${err.message}`);
}
```