API error handling

Response shape

Use a consistent JSON body:

{
  "error": "forbidden",
  "message": "You do not have access to this project."
}

Optional details for validation (api-error-handling + server-input-validation).

Edge helper

function jsonError(status: number, error: string, message: string) {
  return new Response(JSON.stringify({ error, message }), {
    status,
    headers: { "Content-Type": "application/json" },
  });
}

Supabase errors

const { error } = await supabase.from("posts").insert(row);
if (error) {
  if (error.code === "23505") return jsonError(409, "conflict", "Already exists");
  if (error.code === "42501") return jsonError(403, "forbidden", "Not allowed");
  console.error(error);
  return jsonError(500, "internal_error", "Something went wrong");
}

Logging

• console.error with correlation id (crypto.randomUUID() in response header x-request-id).
• Never log passwords, tokens, full card data.

Client consumption

Hooks/forms map error slug to toast; show message to users, not raw DB text.

Avoid

• 200 with { success: false } for errors.
• Leaking error.message from Postgres in production.
• Empty catch {} blocks.

Checklist

• All edge paths return JSON errors, not HTML
• 500 messages are generic; details in logs only