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

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

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.