API Errors

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

Error Response Body

1{
2  "error": {
3    "code": "rate_limit_exceeded",
4    "message": "Too many requests. Please try again in 300 seconds.",
5    "doc_url": "https://docs.betterdata.co/reference/error-handling"
6  }
7}

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:

1try {
2  const result = await gateway.execute(toolCall);
3} catch (e) {
4  if (e.code === 'rate_limit_exceeded') {
5    "cmt">// Implement backoff or notify user
6  } else if (e.code === 'auth_required') {
7    "cmt">// Trigger login flow
8  }
9}

For more detailed information on how the gateway communicates these errors back to the AI model, see the Reference -> Error Handling guide.