Errors

HTTP status codes

400 invalid request, 401 token/signature, 403 permissions or quota, 404 unavailable resource, 409 name conflict, 413 file too large, 422 field validation, 429 rate limit, and 5xx temporary platform failure.

Retrying

Retry only idempotent operations and 429/5xx responses with exponential backoff and jitter. Always provide idempotency_key when posting messages.

Chat failures

A failed callback restores the button and displays a system message. Never publish stack traces or raw webhook errors into a chat.

SDK practice

Separate permanent 4xx failures from transient 429/5xx responses. Retry with exponential backoff and jitter while preserving the original idempotency_key.

Log request id, status, and a safe response summary, but redact tokens, webhook secrets, and user attachments.

import { KeyChatError } from '@keychat/bots';

try { await bot.sendMessage(input); }
catch (error) {
  if (error instanceof KeyChatError && (error.status === 429 || error.status >= 500)) scheduleRetry(input);
  else throw error;
}