Error handling

Catch typed LumaError exceptions from the @alhwyn/luma TypeScript SDK, including HTTP status codes and response body details for failed API requests.

Failed API requests throw typed errors from @alhwyn/luma. All errors extend LumaError and include status and optional body from the API response.

Error types

Class	HTTP status	When
ValidationError	400	Invalid request parameters or body
AuthenticationError	401	Missing or invalid API key
RateLimitError	429	Rate limit exceeded
WebhookSignatureError	401	Webhook signature verification failed
LumaError	other	Any other non-2xx response

Webhook verification errors

Inbound webhook verification throws WebhookSignatureError when the signature is missing, expired, or invalid:

import { WebhookSignatureError } from "@alhwyn/luma";

try {
  webhook.verify({ body, headers });
} catch (error) {
  if (error instanceof WebhookSignatureError) {
    return new Response("Unauthorized", { status: 401 });
  }
  throw error;
}

Inspecting error bodies

The API sometimes returns extra detail in the response body:

catch (error) {
  if (error instanceof ValidationError) {
    console.log(error.status); // 400
    console.log(error.body);   // raw API JSON, if present
  }
}