Gateway Error Handling

Unicode-safe error handling for Gateway bot replies with root-cause extraction

Gateway error handling automatically sanitises exception text to prevent encoding crashes while preserving meaningful error information for users.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="Help the user",
    model="gpt-4o-mini",
)
# Gateway bots receive clean ASCII-safe errors — not raw stack traces
agent.start("What's the weather?")

The user sends a message that triggers an internal error; the gateway sanitises the exception to ASCII-safe text in the reply while logging full detail.

Quick Start

1. Simple Usage

   Error handling is automatic — no configuration needed. When agents throw exceptions containing Unicode characters, the gateway safely converts them for bot replies.

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Assistant",
       instructions="Help the user",
       model="gpt-4o-mini"
   )
   # When the agent hits an API error (quota, rate limit, auth, timeout),
   # the gateway sends the user a clean message — not a stack trace.
   agent.start("What's the weather?")

2. Test Error Handling

   Verify your version includes Unicode-safe error handling:

   python -c "from praisonai_bot.gateway.unicode_utils import safe_error_message; print('OK')"

   If this runs without error, your install includes the ASCII-safe error sanitizer (originally PraisonAI PR #1754; extended in PR #3430 to strip box-drawing frame characters).

How It Works

The gateway processes exceptions in three stages:

1. Root-cause extraction — identifies the underlying API error
2. Unicode sanitization — converts symbols to ASCII-safe equivalents
3. Safe reply — sends clean message to user via bot

Related Helpers

The unicode_utils module exports two sibling helpers alongside safe_error_message.

Configuration Options

Error handling is automatic with no required configuration. The feature is included in PraisonAI versions containing PR #1754.

Structured Connection Errors

The hello handshake returns machine-readable ConnectErrorCode values (auth_required, auth_unauthorized, protocol_unsupported, pairing_required, agent_not_found) with optional next_action hints — instead of free-text-only connection failures.

Codes fall into two client-side classes: transient (rate_limited — back off and retry) and terminal (auth_required, auth_unauthorized, pairing_required, protocol_unsupported, agent_not_found, origin_not_allowed, configuration_error — reconnect loop stops until an operator intervenes). See Gateway Client → Terminal vs Transient Connect Errors for how GatewayClient handles each class and the on_reconnect_paused callback.

See Gateway Handshake Protocol for the full error matrix and capability negotiation.

Structured turn-failure error (wire)

The Unicode sanitiser protects chat-reply text; the typed outcome.error on the final response frame protects programmatic clients (operator UIs, OpenAI-compat consumers, custom bots).

The end-user text comes from a fixed per-code table (_TURN_ERROR_MESSAGES), never str(e). See Gateway Turn Error Codes for the full code vocabulary.

Reconnect After Disconnect

Pending inbox messages and in-flight executions are preserved when a WebSocket disconnects. On reconnect with the same session_id, the client receives a status frame:

{
  "type": "status",
  "message": "Resuming processing (2 pending messages)..."
}

Queued messages are processed in FIFO order. See Gateway Session Continuity for drain behaviour and persisted session shape.

Common Patterns

Recognized Error Types

The gateway automatically recognizes and formats these error patterns:

• <msg> (OpenAI format) | Error

: <msg> | | HTTP

: <msg> | Error

: <msg> | | Contains quota (exceeded / insufficient) | API quota exceeded. Check billing. | | Contains rate limit (exceeded) | Rate limit exceeded. Try again later. | | Contains authentication (failed) | Authentication failed. Check API key. | | Contains timeout | Request timeout. Try again.` | | (anything else) | Original error text, sanitized to ASCII |

Symbol Replacements

Unicode symbols are replaced with ASCII equivalents:

Accented letters (á, é, ñ, etc.) are converted to their base forms (a, e, n).

Before vs After

Before PR #1754 (broken on Windows):

User sees: 'charmap' codec can't encode character '⚠' in position 27: character maps to <undefined>

After PR #1754 (safe on all platforms):

User sees: API quota exceeded. Check billing.

Before PR #3430 (cluttered ? placeholders around the frame on Windows cp1252):

User sees: ? Please run: playwright install ?

After PR #3430 (frame collapses to spaces, hint stays readable):

User sees: Please run: playwright install

Best Practices

praisonai gateway logs

# Users see: "API quota exceeded. Check billing."
# Solution: Add credits at platform.openai.com

# Test with Unicode in agent instructions or error messages
agent = Agent(
    name="Test",
    instructions="Handle errors with Unicode: ⚠️ warnings, ✅ success",
    model="gpt-4o-mini"
)

Related