Gateway Turn Error Codes

Typed error payload on the final response frame when a gateway turn fails

When a turn fails, the final response frame carries a typed outcome.error, so a chat UI can show the right Retry or Stop button and a safe message instead of a raw provider traceback.

Quick Start

1. Read outcome.error on a final response

   import asyncio
   from praisonai_bot.gateway.client import GatewayClient
   
   async def main():
       client = GatewayClient(url="ws://localhost:8765", agent_id="my-agent")
       await client.connect()
       await client.send("Summarise today's news")
   
       async for event in client.events():
           frame = event.data
           if event.type == "response" and frame.get("status") == "final":
               outcome = frame["outcome"]
               if outcome["status"] == "error":
                   err = outcome.get("error", {})
                   print(err.get("code"), "-", err.get("message"))
               break
   
   asyncio.run(main())

2. Retry only when retryable

   import asyncio
   from praisonai_bot.gateway.client import GatewayClient
   
   async def ask(client, text):
       await client.send(text)
       async for event in client.events():
           frame = event.data
           if event.type == "response" and frame.get("status") == "final":
               return frame
   
   async def main():
       client = GatewayClient(url="ws://localhost:8765", agent_id="my-agent")
       await client.connect()
   
       for attempt in range(3):
           frame = await ask(client, "Summarise today's news")
           outcome = frame["outcome"]
           err = outcome.get("error")
           if outcome["status"] != "error" or not err or not err["retryable"]:
               break
           await asyncio.sleep(err["retry_after_seconds"] or 2 ** attempt)
   
       print(frame["content"])
   
   asyncio.run(main())

How It Works

The gateway classifies the exception, picks a fixed safe message for its code, and attaches the result to the final frame.

{
  "type": "response",
  "status": "final",
  "content": "Error: ...",
  "outcome": {
    "status": "error",
    "error": {
      "code": "rate_limit",
      "retryable": true,
      "retry_after_seconds": 30,
      "message": "Rate limited by the model provider. Please retry shortly."
    }
  },
  "session_id": "..."
}

Error Codes

Common Patterns

import asyncio

async def handle(frame):
    err = frame["outcome"].get("error")
    if err and err["retryable"]:
        await asyncio.sleep(err["retry_after_seconds"] or 2)
        return "retry"
    return "stop"

def next_step(err):
    code = err["code"]
    if code == "context_overflow":
        return "Start a new chat"
    if code == "billing":
        return "Top up your credit"
    if code in ("auth", "auth_permanent"):
        return "Re-authenticate"
    return err["message"]

const ws = new WebSocket("ws://localhost:8765");

ws.onmessage = (msg) => {
  const frame = JSON.parse(msg.data);
  if (frame.type !== "response" || frame.status !== "final") return;

  const err = frame.outcome.error;
  if (frame.outcome.status === "error" && err?.retryable) {
    setTimeout(() => resend(), (err.retry_after_seconds ?? 2) * 1000);
  }
};

User Interaction Flow

The user sees a spinner, a short “Retrying” notice, then the answer.

Best Practices

Related