Backend · Skill

Handle errors gracefully

handle-errors-gracefully

Adds sensible error handling to an app - separate expected errors from bugs, show friendly messages to users, log the details with context, retry only what is safe, and stop one failing service from taking the whole app down. Use when the app crashes on bad input, users see raw stack traces, or errors are swallowed and nothing gets logged.

Works with: Any AI Not yet model-tested; testing Jan 2027

View raw SKILL.mdInstall

Paste it into ChatGPT, Claude, Gemini or any AI chat, then tell it about your project. How it works

Install in Claude Code, Cursor or Codex (optional)

Only for AI coding tools that read skill folders. Run one line in a terminal, in your project folder. It downloads this skill's text files from TheSkillVault and nothing else; you can read them first with “View raw SKILL.md”.

Claude Code (all your projects)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/handle-errors-gracefully/raw' -o ~/'.claude/skills/handle-errors-gracefully/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/handle-errors-gracefully/files/LICENSE.txt' -o ~/'.claude/skills/handle-errors-gracefully/LICENSE.txt'

Cursor (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/handle-errors-gracefully/raw' -o '.cursor/skills/handle-errors-gracefully/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/handle-errors-gracefully/files/LICENSE.txt' -o '.cursor/skills/handle-errors-gracefully/LICENSE.txt'

Codex and other Agent Skills tools (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/handle-errors-gracefully/raw' -o '.agents/skills/handle-errors-gracefully/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/handle-errors-gracefully/files/LICENSE.txt' -o '.agents/skills/handle-errors-gracefully/LICENSE.txt'

Or connect the whole library over MCP

Add TheSkillVault to Cursor or add this to your app's MCP settings (read-only; help):

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

Errors will happen. The goal is that users see a clear message, you see the details, and one failure does not break everything.

When to use

  • Users see stack traces, blank screens or "undefined" messages.
  • Errors are caught and ignored, so bugs go unnoticed.
  • Calls to a payment, email or AI provider fail now and then.

Steps

  1. Sort errors into two kinds: expected (bad input, not found, not allowed) and unexpected (bugs, outages).
  2. For expected errors, return a clear message and the right status code. Do not log them as alarms.
  3. For unexpected errors, show a generic message ("Something went wrong, try again") and log the full detail.
  4. Add one top-level handler (Express error middleware, a Next.js error.tsx, a FastAPI exception handler) so nothing escapes raw.
  5. Log with context: route, user id, request id, and the error with its stack.
  6. Never swallow errors. An empty catch {} must at least log or re-throw.
  7. Retry only safe, temporary failures (timeouts, 429, 503) with backoff, and cap the attempts.
  8. Set timeouts on every outside call so one slow service cannot hang a request.
  9. Show partial results where possible, such as the page without the broken widget.
  10. Send unexpected errors to a tracker such as Sentry, and check it after each release.
try {
  await sendReceipt(order);
} catch (err) {
  logger.error({ err, orderId: order.id }, "receipt email failed");
  // order is still saved; the receipt can be retried later
}

Gotchas

  • Never put passwords, tokens, API keys or full card numbers in logs or error messages.
  • Do not retry a payment or anything else that is not safe to repeat unless it uses an idempotency key.
  • Error messages that say "user not found" vs "wrong password" help attackers. Use one message for failed sign-ins.
  • Catching too high up hides where the problem started. Keep the original error as the cause.

Portability

Works with any language. If you use Python, Go or Rust instead of JavaScript, the same split of expected and unexpected errors applies with that language's equivalent of try/catch or result types.

Example prompt

"My API crashes and shows stack traces when something fails. Add proper error handling, friendly messages and logging."

Done when

  • No route can return a raw stack trace to a user.
  • Unexpected errors are logged with context and no secrets.
  • Outside calls have timeouts, and only safe calls are retried.

---

Adapted from "error-handling-patterns" in wshobson/agents (MIT, Copyright (c) 2024 Seth Hobson). See LICENSE.txt.

Bundled files

Licence

Adapted from Seth Hobson (wshobson/agents, error-handling-patterns) (Copyright (c) 2024 Seth Hobson), MIT License. Adapted by TheSkillVault: rewritten as a beginner checklist with original examples; dropped the multi-language pattern catalogue; added secret-safe logging, gotchas and done-when.

Licence: MIT License. Attribution when you reuse it: Based on work by Seth Hobson (wshobson/agents, error-handling-patterns) (Copyright (c) 2024 Seth Hobson, MIT License), https://github.com/wshobson/agents/tree/7e2fb559cf4b824b27f1fec49fe88f7511066d26/plugins/developer-essentials/skills/error-handling-patterns; adapted by TheSkillVault, https://theskillvault.ai