> ## 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.

# API Errors

> Structure and meaning of error responses

When the LLM Gateway API encountered an error, it returns a standard JSON response with an appropriate HTTP status code.

## Error Response Body

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again in 300 seconds.",
    "doc_url": "https://docs.betterdata.co/reference/error-handling"
  }
}
```

## Common Error Codes

| Status | Code                  | Description                                                     |
| ------ | --------------------- | --------------------------------------------------------------- |
| 400    | `invalid_request`     | The request body is malformed or missing required fields.       |
| 401    | `unauthorized`        | The API key or session ID is invalid.                           |
| 403    | `forbidden`           | You don't have permission to call this tool on this merchant.   |
| 404    | `not_found`           | The requested resource (product, cart, session) does not exist. |
| 429    | `rate_limit_exceeded` | You have reached your account or session quota.                 |
| 500    | `internal_error`      | An unexpected error occurred within the gateway.                |
| 503    | `service_unavailable` | The gateway is temporarily overloaded or in maintenance mode.   |

## Handling Errors in Code

We recommend using a structured error handler to catch and react to specific codes:

```typescript theme={null}
try {
  const result = await gateway.execute(toolCall);
} catch (e) {
  if (e.code === 'rate_limit_exceeded') {
    // Implement backoff or notify user
  } else if (e.code === 'auth_required') {
    // Trigger login flow
  }
}
```

For more detailed information on how the gateway communicates these errors back to the AI model, see the [Reference -> Error Handling](/reference/error-handling) guide.