Supabase Edge Function Error Handling — Retries, Logging, and Idempotency
Design patterns to prevent errors from being swallowed silently in production EFs.
Basics: Return Structured Errors
// supabase/functions/_shared/error.ts
export class AppError extends Error {
constructor(
message: string,
public readonly code: string,
public readonly status: number = 500,
) {
super(message);
}
}
export function errorResponse(error: unknown): Response {
if (error instanceof AppError) {
return new Response(
JSON.stringify({ error: error.message, code: error.code }),
{ status: error.status, headers: { 'Content-Type': 'application/json' } },
);
}
console.error('Unexpected error:', error);
return new Response(
JSON.stringify({ error: 'Internal server error', code: 'INTERNAL' }),
{ status: 500, headers: { 'Content-Type': 'application/json' } },
);
}
Fetch with Retry
async function fetchWithRetry(
url: string,
options: RequestInit,
maxRetries = 3,
): Promise<Response> {
let lastError: Error | undefined;
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const res = await fetch(url, options);
if (res.status === 429) {
// Rate limit: exponential backoff
const wait = Math.pow(2, attempt) * 1000;
await new Promise(r => setTimeout(r, wait));
continue;
}
if (!res.ok && res.status >= 500) {
throw new Error(`HTTP ${res.status}`);
}
return res;
} catch (e) {
lastError = e as Error;
if (attempt < maxRetries) {
await new Promise(r => setTimeout(r, attempt * 500));
}
}
}
throw lastError ?? new Error('Max retries exceeded');
}
Structured Logging
// Common log format across all EFs
function log(level: 'info' | 'warn' | 'error', message: string, meta?: object) {
console.log(JSON.stringify({
level,
message,
timestamp: new Date().toISOString(),
function: Deno.env.get('FUNCTION_NAME') ?? 'unknown',
...meta,
}));
}
// Usage
log('info', 'Processing webhook', { event_type: event.type });
log('error', 'Stripe API failed', { attempt: 3, status: 500 });
Idempotent Webhook Processing
// Prevent double-processing the same event
const { data: processed } = await supabase
.from('processed_webhooks')
.select('id')
.eq('event_id', event.id)
.maybeSingle();
if (processed) {
return new Response('ok'); // silently ignore duplicates
}
// Record after processing
await supabase.from('processed_webhooks').insert({
event_id: event.id,
processed_at: new Date().toISOString(),
});
Summary
Error responses → AppError + errorResponse (structured JSON)
Retries → exponential backoff (for 429 and 5xx)
Logging → structured JSON logs (searchable in Supabase Dashboard)
Idempotency → processed_webhooks table prevents double-processing
Design EFs to be "safe to fail" by default.