Error Handling

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:

1{
2  "error": "product_not_found",
3  "message": "Product 'sku-123' is no longer in the catalog.",
4  "hint": "Try searching again with keywords like 'running shoes' to find a similar item."
5}

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 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:

1const response = await fetch(gatewayUrl, ...);
2if (!response.ok) {
3  const err = await response.json();
4  console.error(`Gateway Error [${err.code}]: ${err.message}`);
5}