Errors and signed webhooks
Handle typed request failures safely and verify signed webhook bytes before decoding events.
Typed API errors
import { ApiError } from '@vchatsdk/sdk-typescript';
try {
await appUser.conversations.query({ limit: 25 });
} catch (error: unknown) {
if (error instanceof ApiError) {
renderSafeFailure({
code: error.code,
statusCode: error.statusCode,
retryAfterSeconds: error.retryAfterSeconds,
requestId: error.requestId,
});
}
}Verify the raw webhook request
import { verifyWebhook } from '@vchatsdk/sdk-typescript/webhooks/server';
const event = verifyWebhook({
headers: request.headers,
rawBody,
secrets: [currentSecret, previousSecret].filter(
(value): value is string => value !== undefined,
),
});
dispatchVerifiedEvent(event);Verify the exact raw bytes before JSON parsing. Enforce the released timestamp tolerance, deduplicate by stable delivery/event identity, return quickly, and move business work to your own durable queue.
Retry decisions
- A retryable error means a future attempt may succeed; it does not prove a mutation is safe to replay.
- Respect positive Retry-After guidance with caller-controlled scheduling.
- For ambiguous fixed-identity mutations, read and reconcile the resource first.
- Treat authentication, authorization, validation, and resource-not-found outcomes as non-retryable until inputs or authority change.