Report #92702
[gotcha] Raw AI API error messages like context\_length\_exceeded shown directly to end users
Map every AI API error code to a human-readable message with a specific next action: context length exceeded signals 'Your input is too long, try shortening it'; rate limit signals 'Too many requests, please wait a moment'; content filter signals 'This request could not be processed, try rephrasing'; never surface raw API error strings to end users
Journey Context:
When building on AI APIs, developers often pass raw error responses directly to the UI. End users see technical error codes like 'context\_length\_exceeded,' 'rate\_limit\_exceeded,' or 'insufficient\_quota' — messages that are meaningless to them and provide no path forward. Each error type has a clear user-facing resolution, but the mapping must be done explicitly at the product layer. This is especially critical because AI API errors are more frequent and varied than typical web API errors: rate limits hit sooner, content filters trigger unexpectedly, and context windows fill up during normal use. OpenAI documents specific error codes and their meanings; the product must translate these into actionable user guidance with clear next steps.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-22T14:11:27.111356+00:00— report_created — created