When it fires
When a request that passed every check fails at the AI provider, on both paths:
- Not streamed: when the provider call throws, for example a wrong API key, a model that does not exist, a rate limit or a timeout.
$codeisai_exception. - Streamed: when the call throws (
ai_exception), when the provider reports an error inside the stream, when the stream ends without an answer and when the provider cannot stream (ai_stream_error, and$context['exception']is null). The action fires after the visitor got the error event and before the stream closes. If the AI environment cannot be resolved before the stream starts, it fires withai_exceptiontoo.
$context['normalized_error'] is KimaAI’s view of the error, the same on both paths: provider, userMessage (what the visitor sees), message, type, code, param, status, retryable (true for 408, 409, 429 and 5xx) and rawMessage. ai_payload and payload are those of the request, with $context['payload']['assistantSurface'] admin_assistant or search outside the chat.
Refusals before the provider (the gate, the daily limit, the maximum message length) do not fire it. Up to 1.5.13 it fired only when the answer did not stream.
Parameters
| Name | Type | Description |
|---|---|---|
code | string | ai_exception when the provider call threw, ai_stream_error for an error the stream reported. |
message | string | The provider’s error message, for the logs; the visitor sees a message of its own. |
context | array | exception (the Throwable, or null for ai_stream_error), ai_payload, payload and normalized_error. |
Example
add_action(
'kimaai_chatbot_error',
function (string $code, string $message, array $context): void {
$error = $context['normalized_error'];
// Rate limits and outages pass; a wrong key or model needs someone.
if (!empty($error['retryable'])) {
return;
}
wp_mail(
get_option('admin_email'),
'The chatbot could not answer',
sprintf("Provider: %s\nStatus: %d\nError: %s", $error['provider'], $error['status'], $message)
);
},
10,
3
);
Related
kimaai_chatbot_after_response: fires instead when the answer arrives.kimaai_chatbot_before_request: fires before the request.kimaai_chatbot_blocked: fires when the gate refuses a message before the provider.