Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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.gateway.unicode_utils import safe_error_message; print('OK')"
If this runs without error, you have the fix from PR #1754.

​
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

​
Configuration Options

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

Gateway Error Handling Reference

Source implementation details in PraisonAI PR #1754

​
Common Patterns

​
Recognized Error Types

The gateway automatically recognizes and formats these error patterns:
Pattern matched in exceptionUser-facing reply
Error code: <N> - <msg> (OpenAI format)Error <N>: <msg>
HTTP <N>: <msg>Error <N>: <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 timeoutRequest timeout. Try again.
(anything else)Original error text, sanitized to ASCII

​
Symbol Replacements

Unicode symbols are replaced with ASCII equivalents:
UnicodeASCIIDescription
⚠!Warning symbol
✓OKCheck mark
✗XCross mark
→->Right arrow
…...Ellipsis
" ""Smart quotes
— –-- -Em/en dash
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.

​
Best Practices

Full Unicode exception details are preserved in gateway logs for debugging while users see clean ASCII-safe messages.
praisonai gateway logs
Set up billing alerts and monitor usage to prevent quota exceeded errors:
# Users see: "API quota exceeded. Check billing."
# Solution: Add credits at platform.openai.com
The Unicode-safe error handling works on Windows, macOS, and Linux:
# Test with Unicode in agent instructions or error messages
agent = Agent(
    name="Test",
    instructions="Handle errors with Unicode: ⚠️ warnings, ✅ success",
    model="gpt-4o-mini"
)
No workaround needed on supported versions. Previously recommended environment variables (PYTHONUTF8=1) are no longer required for the bot reply path.

Gateway Troubleshooting

Troubleshoot Windows charmap errors and other gateway issues

Bot Gateway

Configure multiple bots with the gateway server