What causes "Responses API error [{code}]: {msg}" in Hmbown/CodeWhale?

Read the bracketed code first - it maps to the provider's documented error taxonomy

Responses API error [{code}]: {msg}

Error message

Responses API error [{code}]: {msg}

What it means

The provider's Responses-API stream delivered an event of type error or response.failed after the stream was already underway. responses_event_error_details extracts a machine code and human message, and the client terminates with 'Responses API error [code]: msg' (crates/tui/src/client/responses.rs:502) instead of treating the response as complete. DeepSeek deliberately ends semantic Responses streams this way instead of sending data: [DONE].

Source

Thrown at crates/tui/src/client/responses.rs:502

                                            Some(parse_responses_usage(usage_val));
                                    }
                                    let stop_reason = responses_stop_reason(resp, saw_tool_call);
                                    yield Ok(StreamEvent::MessageDelta {
                                        delta: MessageDelta {
                                            stop_reason: Some(stop_reason),
                                            stop_sequence: None,
                                        },
                                        usage: usage_data.take(),
                                    });
                                }
                                // DeepSeek terminates semantic Responses
                                // streams with this event and deliberately does
                                // not send `data: [DONE]`.
                                done = true;
                            }
                            "error" | "response.failed" => {
                                let (code, msg) = responses_event_error_details(&event);
                                yield Err(anyhow::anyhow!(
                                    "Responses API error [{code}]: {msg}"
                                ));
                                return;
                            }
                            _ => {
                                // Ignore unknown event types.
                            }
                        }
                    }
                }
            }

            // Emit MessageStop.
            yield Ok(StreamEvent::MessageStop);
        };

        Ok(Box::pin(stream))
    }

View on GitHub (pinned to 8880682c63)

Solutions

Read the bracketed code first - it maps to the provider's documented error taxonomy
Verify the key can call this exact model with a plain non-streaming curl
For permission/content codes, fix the request payload (tools, instructions); do not retry
Retry with backoff only for overload/timeout-style codes - auth and validation codes fail identically
If a gateway fronts the provider, test the provider directly to see which side synthesized the event

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight the same model non-streaming to surface auth/model errors before the stream
let resp = client.post("/responses").json(&minimal_request_for(model)).send().await?;
ensure!(resp.status().is_success(), "pre-flight failed: {}", resp.status());

Type guard

fn is_responses_api_error(msg: &str) -> bool {
    msg.starts_with("Responses API error [")
}

fn responses_error_code(msg: &str) -> Option<&str> {
    msg.strip_prefix("Responses API error [")?.split(']').next()
}

Try / catch

// Branch on the bracketed code: retry overload, fail fast on auth/validation
if let Some(code) = responses_error_code(&e.to_string()) {
    match code {
        "overloaded_error" | "timeout" => retry_with_backoff().await,
        _ => return Err(e), // 4xx-class codes are deterministic
    }
}

Prevention

Pre-flight model access with a tiny non-streaming call when switching keys
Keep tool schemas valid - some providers only validate them mid-stream
Map provider error codes to retry policies instead of retrying everything

When it happens

Trigger: Mid-stream failures after a 200: content-policy rejections once output starts, model not enabled for this account, provider overload, tool definitions that only fail at execution time, or a genuine response.failed terminal event.

Common situations: API key scoped to models it cannot serve; org rate-limited mid-generation; Responses-API emulation gateways that fail on tool calls; expired keys that pass header auth but fail on the event bus.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/335f0cd643a6b69b. Report an issue: GitHub.