🏷️ v1.0.3 — Actionable Suggestions for Every Error

What's New

Every AppError now includes a suggestion field — a required, always-present string that provides actionable, user-friendly advice on how to resolve the error.

While message tells users what went wrong, suggestion tells them what to do about it.

Example Output

{
  "kind": "http",
  "message": "Not Found",
  "suggestion": "The requested resource could not be found. Please verify your request.",
  "status": 404,
  "retryable": false
}

{
  "kind": "network",
  "message": "Something went wrong",
  "suggestion": "Please check your internet connection and try again.",
  "retryable": true
}

Default Suggestions

HTTP Errors (configurable via defineErrorPolicy)

Status	Suggestion
400	Please review your request and ensure all fields are correct.
401	Please ensure you have valid credentials and try again.
403	You do not have permission to perform this action.
404	The requested resource could not be found. Please verify your request.
408	The request took too long. Please try again shortly.
409	A conflict occurred. Please refresh and try again.
422	Some of the provided data is invalid. Please review your input.
429	Too many requests. Please wait a moment and try again.
500	An internal server error occurred. Please try again later or contact support.
502	The server received an invalid response. Please try again later.
503	The service is temporarily unavailable. Please try again later.
504	The server did not respond in time. Please try again later.

Non-HTTP Errors (built-in)

Kind	Suggestion
network	Please check your internet connection and try again.
timeout	The request took too long. Please try again shortly.
parse	The server returned an unexpected response. Please try again or contact support.
validation	Please review your input and correct any errors.
unknown	An unexpected error occurred. Please try again or contact support.

Custom Suggestions Per Backend

Override defaults using defineErrorPolicy:

const policy = defineErrorPolicy({
  http: {
    suggestion: (status, data) => {
      if (status === 404) return "The item may have been deleted. Check your dashboard.";
      if (status === 503) return "We're performing maintenance. Back soon!";
      // Falls back to defaults for other statuses
    },
  },
});

Breaking Changes

• suggestion is now a required field on AppError (previously absent). If you construct AppError objects manually, you must include suggestion.
• isAppError() now checks for suggestion being a string.

Files Changed

• src/types.ts — suggestion: string added to AppError
• src/policy.ts — suggestion extractor added to HttpPolicy
• src/toAppError.ts — suggestion wired into all error paths
• src/fromFetch.ts — suggestion wired into fetch error path
• package.json — version bumped to 1.0.3