API Reference
captureMessage
Report an arbitrary message — no Error object required. Useful for soft failures, retries that succeeded, and noteworthy state transitions.
Signature#
typescript
function captureMessage(
message: string,
options?: CaptureMessageOptions,
): string | null;
interface CaptureMessageOptions {
severity?: 'low' | 'medium' | 'high' | 'critical';
tags?: Record<string, string | number | boolean>;
}Parameters#
| Name | Type | Default | Description |
|---|---|---|---|
| message* | string | — | The message to report. Will be used for fingerprinting and grouping in the dashboard. |
| options.severity | enum | 'medium' | low | medium | high | critical. |
| options.tags | object | — | Per-call tags merged over scope tags. |
When to use this vs. captureException#
Use captureException when you have a real Error object — a try/catch caught something, a Promise rejected, etc. Use captureMessage when the situation is worth reporting but isn't an exception. The dashboard groups them together so you can filter by severity, but the source distinction is preserved.
Examples#
typescript
// Soft failure that recovered
captureMessage('payment retry succeeded after 3 attempts', {
severity: 'low',
tags: { retry_count: '3', flow: 'checkout' },
});
// Noteworthy state transition
captureMessage('user activated experimental feature', {
severity: 'low',
tags: { feature: 'ai-search' },
});
// Validation that should not have been reachable
if (!['draft', 'published', 'archived'].includes(post.status)) {
captureMessage(`unexpected post status: ${post.status}`, {
severity: 'high',
});
}Return value#
Returns the event UUID as a string, or null if the SDK isn't initialized, the message was de-duped, or beforeSend dropped it. De-duplication uses the same 5-second fingerprint window as errors — so flooding captureMessage in a loop is safe.
Stack trace
A synthetic stack trace is captured at the call site so the dashboard can show you where the message originated, even though there was no thrown error.