kimaai_chatbot_error

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. $code is ai_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 with ai_exception too.

$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

NameTypeDescription
codestringai_exception when the provider call threw, ai_stream_error for an error the stream reported.
messagestringThe provider’s error message, for the logs; the visitor sees a message of its own.
contextarrayexception (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
);
  • 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.

What are your feelings