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

Error Response Body

{
  "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

StatusCodeDescription
400invalid_requestThe request body is malformed or missing required fields.
401unauthorizedThe API key or session ID is invalid.
403forbiddenYou don’t have permission to call this tool on this merchant.
404not_foundThe requested resource (product, cart, session) does not exist.
429rate_limit_exceededYou have reached your account or session quota.
500internal_errorAn unexpected error occurred within the gateway.
503service_unavailableThe 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:
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 guide.