mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
Every page now loads /webmcp.js, scripts/webmcp.ts with its types stripped (npm run webmcp). Where the browser has document.modelContext it registers two read-only tools: search_skills over the published skills index, and get_skill, which returns a skill's markdown checked against the index digest. The markdown alternate link moves from build.py to site.py, so CI holds every page to it. The API catalog gains the site itself (llms.txt and the skills index) and hanzo.ai/agents; the live discovery check now fetches every catalog link. tests/site.mjs drives the tools through a recording modelContext, and checks a browser without one loads clean.
832 lines
34 KiB
HTML
832 lines
34 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>api-api-error-handling</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant โ
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/api-api-error-handling">
|
|
<link rel="alternate" type="text/markdown" href="/api-api-error-handling.md">
|
|
<script type="module" src="/webmcp.js"></script>
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/api-api-error-handling.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>api-api-error-handling</h1><p class="lede">Designing error responses for REST APIs</p><h1>API Error Handling</h1>
|
|
<p><strong>Use this skill when:</strong></p>
|
|
<ul><li>Designing error responses for REST APIs</li><li>Handling validation errors in API endpoints</li><li>Implementing consistent error formatting</li><li>Building user-friendly error messages</li><li>Setting up error logging and correlation</li><li>Choosing appropriate HTTP status codes</li></ul>
|
|
<h2>Error Response Structure</h2>
|
|
<h3>Standard Error Format</h3>
|
|
<p>Design a consistent error response structure:</p>
|
|
<pre><code class="lang-typescript">interface ErrorResponse {
|
|
code: string; // Machine-readable error code
|
|
message: string; // Human-readable message
|
|
details?: ErrorDetail[]; // Additional context
|
|
trace_id?: string; // Request correlation ID
|
|
timestamp: string; // ISO 8601 timestamp
|
|
}
|
|
|
|
interface ErrorDetail {
|
|
field?: string; // Field name for validation errors
|
|
message: string; // Specific error message
|
|
code?: string; // Field-specific error code
|
|
}
|
|
|
|
// Example response
|
|
{
|
|
"code": "VALIDATION_ERROR",
|
|
"message": "Request validation failed",
|
|
"details": [
|
|
{
|
|
"field": "email",
|
|
"message": "Invalid email format",
|
|
"code": "INVALID_FORMAT"
|
|
},
|
|
{
|
|
"field": "age",
|
|
"message": "Must be at least 18",
|
|
"code": "MIN_VALUE"
|
|
}
|
|
],
|
|
"trace_id": "a1b2c3d4-e5f6-7890",
|
|
"timestamp": "2025-10-18T10:30:00Z"
|
|
}</code></pre>
|
|
<h3>Python/FastAPI Implementation</h3>
|
|
<pre><code class="lang-python">from fastapi import FastAPI, HTTPException, Request
|
|
from fastapi.responses import JSONResponse
|
|
from fastapi.exceptions import RequestValidationError
|
|
from pydantic import BaseModel, ValidationError
|
|
from typing import Optional, List
|
|
from datetime import datetime
|
|
import uuid
|
|
|
|
app = FastAPI()
|
|
|
|
class ErrorDetail(BaseModel):
|
|
field: Optional[str] = None
|
|
message: str
|
|
code: Optional[str] = None
|
|
|
|
class ErrorResponse(BaseModel):
|
|
code: str
|
|
message: str
|
|
details: Optional[List[ErrorDetail]] = None
|
|
trace_id: str
|
|
timestamp: str
|
|
|
|
@classmethod
|
|
def create(
|
|
cls,
|
|
code: str,
|
|
message: str,
|
|
details: Optional[List[ErrorDetail]] = None,
|
|
trace_id: Optional[str] = None
|
|
):
|
|
return cls(
|
|
code=code,
|
|
message=message,
|
|
details=details,
|
|
trace_id=trace_id or str(uuid.uuid4()),
|
|
timestamp=datetime.utcnow().isoformat() + "Z"
|
|
)
|
|
|
|
@app.exception_handler(RequestValidationError)
|
|
async def validation_exception_handler(
|
|
request: Request,
|
|
exc: RequestValidationError
|
|
):
|
|
details = []
|
|
for error in exc.errors():
|
|
field = ".".join(str(loc) for loc in error["loc"][1:])
|
|
details.append(ErrorDetail(
|
|
field=field,
|
|
message=error["msg"],
|
|
code=error["type"].upper()
|
|
))
|
|
|
|
error_response = ErrorResponse.create(
|
|
code="VALIDATION_ERROR",
|
|
message="Request validation failed",
|
|
details=details
|
|
)
|
|
|
|
return JSONResponse(
|
|
status_code=422,
|
|
content=error_response.model_dump()
|
|
)
|
|
|
|
@app.exception_handler(HTTPException)
|
|
async def http_exception_handler(request: Request, exc: HTTPException):
|
|
error_response = ErrorResponse.create(
|
|
code=get_error_code_for_status(exc.status_code),
|
|
message=exc.detail
|
|
)
|
|
|
|
return JSONResponse(
|
|
status_code=exc.status_code,
|
|
content=error_response.model_dump()
|
|
)
|
|
|
|
def get_error_code_for_status(status: int) -> str:
|
|
"""Map HTTP status to error code"""
|
|
codes = {
|
|
400: "BAD_REQUEST",
|
|
401: "UNAUTHORIZED",
|
|
403: "FORBIDDEN",
|
|
404: "NOT_FOUND",
|
|
409: "CONFLICT",
|
|
422: "VALIDATION_ERROR",
|
|
429: "RATE_LIMIT_EXCEEDED",
|
|
500: "INTERNAL_ERROR",
|
|
503: "SERVICE_UNAVAILABLE"
|
|
}
|
|
return codes.get(status, "UNKNOWN_ERROR")</code></pre>
|
|
<h2>HTTP Status Code Selection</h2>
|
|
<h3>Common Status Codes</h3>
|
|
<p>Choose appropriate status codes for different errors:</p>
|
|
<pre><code class="lang-python">from enum import IntEnum
|
|
|
|
class HTTPStatus(IntEnum):
|
|
# 2xx Success
|
|
OK = 200 # Request succeeded
|
|
CREATED = 201 # Resource created
|
|
NO_CONTENT = 204 # Success, no response body
|
|
|
|
# 4xx Client Errors
|
|
BAD_REQUEST = 400 # Invalid request format
|
|
UNAUTHORIZED = 401 # Missing/invalid authentication
|
|
FORBIDDEN = 403 # Authenticated but no permission
|
|
NOT_FOUND = 404 # Resource doesn't exist
|
|
METHOD_NOT_ALLOWED = 405 # HTTP method not supported
|
|
CONFLICT = 409 # Resource state conflict
|
|
GONE = 410 # Resource permanently deleted
|
|
UNPROCESSABLE_ENTITY = 422 # Validation error
|
|
TOO_MANY_REQUESTS = 429 # Rate limit exceeded
|
|
|
|
# 5xx Server Errors
|
|
INTERNAL_ERROR = 500 # Unexpected server error
|
|
NOT_IMPLEMENTED = 501 # Feature not implemented
|
|
SERVICE_UNAVAILABLE = 503 # Temporary unavailability
|
|
GATEWAY_TIMEOUT = 504 # Upstream timeout
|
|
|
|
# Usage examples
|
|
@app.post("/users")
|
|
async def create_user(user: UserCreate):
|
|
if await user_exists(user.email):
|
|
raise HTTPException(
|
|
status_code=HTTPStatus.CONFLICT,
|
|
detail="User with this email already exists"
|
|
)
|
|
|
|
return await create_user_record(user)
|
|
|
|
@app.get("/users/{user_id}")
|
|
async def get_user(user_id: str):
|
|
user = await find_user(user_id)
|
|
if not user:
|
|
raise HTTPException(
|
|
status_code=HTTPStatus.NOT_FOUND,
|
|
detail=f"User {user_id} not found"
|
|
)
|
|
|
|
return user</code></pre>
|
|
<h2>Validation Error Formatting</h2>
|
|
<h3>Field-Level Validation</h3>
|
|
<p>Format validation errors clearly:</p>
|
|
<pre><code class="lang-python">from pydantic import BaseModel, Field, validator, EmailStr
|
|
from typing import List
|
|
|
|
class UserCreate(BaseModel):
|
|
email: EmailStr
|
|
password: str = Field(..., min_length=8, max_length=100)
|
|
age: int = Field(..., ge=18, le=120)
|
|
tags: List[str] = Field(default=[], max_items=10)
|
|
|
|
@validator("password")
|
|
def validate_password(cls, v):
|
|
if not any(c.isupper() for c in v):
|
|
raise ValueError("Password must contain uppercase letter")
|
|
if not any(c.isdigit() for c in v):
|
|
raise ValueError("Password must contain digit")
|
|
return v
|
|
|
|
# Produces error like:
|
|
{
|
|
"code": "VALIDATION_ERROR",
|
|
"message": "Request validation failed",
|
|
"details": [
|
|
{
|
|
"field": "email",
|
|
"message": "value is not a valid email address",
|
|
"code": "VALUE_ERROR_EMAIL"
|
|
},
|
|
{
|
|
"field": "password",
|
|
"message": "Password must contain uppercase letter",
|
|
"code": "VALUE_ERROR"
|
|
},
|
|
{
|
|
"field": "age",
|
|
"message": "ensure this value is greater than or equal to 18",
|
|
"code": "VALUE_ERROR_NUMBER_GE"
|
|
}
|
|
],
|
|
"trace_id": "abc123",
|
|
"timestamp": "2025-10-18T10:30:00Z"
|
|
}</code></pre>
|
|
<h3>Custom Validation Messages</h3>
|
|
<p>Provide user-friendly validation messages:</p>
|
|
<pre><code class="lang-python">class ErrorMessages:
|
|
"""Centralized error messages"""
|
|
|
|
EMAIL_INVALID = "Please enter a valid email address"
|
|
EMAIL_EXISTS = "An account with this email already exists"
|
|
|
|
PASSWORD_TOO_SHORT = "Password must be at least 8 characters"
|
|
PASSWORD_NO_UPPERCASE = "Password must contain an uppercase letter"
|
|
PASSWORD_NO_DIGIT = "Password must contain a number"
|
|
|
|
AGE_TOO_YOUNG = "You must be at least 18 years old"
|
|
AGE_INVALID = "Please enter a valid age"
|
|
|
|
REQUIRED_FIELD = "{field} is required"
|
|
FIELD_TOO_LONG = "{field} must be at most {max} characters"
|
|
|
|
def format_validation_error(field: str, error_type: str, **context) -> str:
|
|
"""Format validation errors with context"""
|
|
messages = {
|
|
"email_invalid": ErrorMessages.EMAIL_INVALID,
|
|
"password_too_short": ErrorMessages.PASSWORD_TOO_SHORT,
|
|
"age_too_young": ErrorMessages.AGE_TOO_YOUNG.format(**context),
|
|
"required": ErrorMessages.REQUIRED_FIELD.format(field=field),
|
|
}
|
|
return messages.get(error_type, f"Validation failed for {field}")</code></pre>
|
|
<h2>User-Friendly vs Developer-Friendly Errors</h2>
|
|
<h3>Dual Error Messages</h3>
|
|
<p>Provide different messages for different audiences:</p>
|
|
<pre><code class="lang-python">class APIError(Exception):
|
|
def __init__(
|
|
self,
|
|
code: str,
|
|
user_message: str,
|
|
dev_message: Optional[str] = None,
|
|
status_code: int = 500,
|
|
details: Optional[List[ErrorDetail]] = None
|
|
):
|
|
self.code = code
|
|
self.user_message = user_message
|
|
self.dev_message = dev_message or user_message
|
|
self.status_code = status_code
|
|
self.details = details
|
|
super().__init__(self.dev_message)
|
|
|
|
@app.exception_handler(APIError)
|
|
async def api_error_handler(request: Request, exc: APIError):
|
|
# Log developer message
|
|
logger.error(
|
|
f"API Error: {exc.code}",
|
|
extra={
|
|
"dev_message": exc.dev_message,
|
|
"trace_id": request.state.trace_id,
|
|
"path": request.url.path,
|
|
}
|
|
)
|
|
|
|
# Return user-friendly message
|
|
error_response = ErrorResponse.create(
|
|
code=exc.code,
|
|
message=exc.user_message, # User sees this
|
|
details=exc.details,
|
|
trace_id=request.state.trace_id
|
|
)
|
|
|
|
return JSONResponse(
|
|
status_code=exc.status_code,
|
|
content=error_response.model_dump()
|
|
)
|
|
|
|
# Usage
|
|
@app.get("/users/{user_id}")
|
|
async def get_user(user_id: str):
|
|
try:
|
|
user = await db.get_user(user_id)
|
|
except DatabaseError as e:
|
|
raise APIError(
|
|
code="DATABASE_ERROR",
|
|
user_message="We're having trouble retrieving your data. Please try again.",
|
|
dev_message=f"Database query failed: {str(e)}",
|
|
status_code=500
|
|
)
|
|
|
|
if not user:
|
|
raise APIError(
|
|
code="USER_NOT_FOUND",
|
|
user_message="We couldn't find a user with that ID",
|
|
dev_message=f"User {user_id} not found in database",
|
|
status_code=404
|
|
)
|
|
|
|
return user</code></pre>
|
|
<h2>Error Logging and Correlation</h2>
|
|
<h3>Request Tracing</h3>
|
|
<p>Implement trace IDs for error correlation:</p>
|
|
<pre><code class="lang-python">from fastapi import Request
|
|
import logging
|
|
import uuid
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
@app.middleware("http")
|
|
async def add_trace_id(request: Request, call_next):
|
|
# Generate or extract trace ID
|
|
trace_id = request.headers.get("X-Trace-ID") or str(uuid.uuid4())
|
|
request.state.trace_id = trace_id
|
|
|
|
response = await call_next(request)
|
|
response.headers["X-Trace-ID"] = trace_id
|
|
|
|
return response
|
|
|
|
@app.exception_handler(Exception)
|
|
async def global_exception_handler(request: Request, exc: Exception):
|
|
trace_id = getattr(request.state, "trace_id", str(uuid.uuid4()))
|
|
|
|
# Log full error details
|
|
logger.exception(
|
|
f"Unhandled exception: {type(exc).__name__}",
|
|
extra={
|
|
"trace_id": trace_id,
|
|
"path": request.url.path,
|
|
"method": request.method,
|
|
"user_agent": request.headers.get("user-agent"),
|
|
"client_ip": request.client.host,
|
|
}
|
|
)
|
|
|
|
# Return sanitized error to client
|
|
error_response = ErrorResponse.create(
|
|
code="INTERNAL_ERROR",
|
|
message="An unexpected error occurred. Please contact support with trace ID.",
|
|
trace_id=trace_id
|
|
)
|
|
|
|
return JSONResponse(
|
|
status_code=500,
|
|
content=error_response.model_dump()
|
|
)</code></pre>
|
|
<h3>Structured Logging</h3>
|
|
<p>Log errors with structured data:</p>
|
|
<pre><code class="lang-python">import structlog
|
|
|
|
logger = structlog.get_logger()
|
|
|
|
async def log_error(
|
|
error: Exception,
|
|
trace_id: str,
|
|
request: Request,
|
|
user_id: Optional[str] = None
|
|
):
|
|
"""Log error with full context"""
|
|
logger.error(
|
|
"api_error",
|
|
error_type=type(error).__name__,
|
|
error_message=str(error),
|
|
trace_id=trace_id,
|
|
path=request.url.path,
|
|
method=request.method,
|
|
status_code=getattr(error, "status_code", 500),
|
|
user_id=user_id,
|
|
user_agent=request.headers.get("user-agent"),
|
|
referer=request.headers.get("referer"),
|
|
)</code></pre>
|
|
<h2>RFC 7807 Problem Details</h2>
|
|
<h3>Standard Problem Format</h3>
|
|
<p>Implement RFC 7807 for errors:</p>
|
|
<pre><code class="lang-python">from pydantic import BaseModel, HttpUrl
|
|
from typing import Optional, Dict, Any
|
|
|
|
class ProblemDetail(BaseModel):
|
|
"""RFC 7807 Problem Details for HTTP APIs"""
|
|
|
|
type: str # URI reference identifying problem type
|
|
title: str # Short, human-readable summary
|
|
status: int # HTTP status code
|
|
detail: Optional[str] = None # Human-readable explanation
|
|
instance: Optional[str] = None # URI reference to specific occurrence
|
|
extensions: Optional[Dict[str, Any]] = None # Additional context
|
|
|
|
class Config:
|
|
json_schema_extra = {
|
|
"example": {
|
|
"type": "https://api.example.com/errors/validation",
|
|
"title": "Validation Error",
|
|
"status": 422,
|
|
"detail": "The request body contains invalid fields",
|
|
"instance": "/users/create",
|
|
"trace_id": "abc-123",
|
|
"invalid_fields": ["email", "age"]
|
|
}
|
|
}
|
|
|
|
@app.exception_handler(RequestValidationError)
|
|
async def rfc7807_validation_handler(
|
|
request: Request,
|
|
exc: RequestValidationError
|
|
):
|
|
invalid_fields = [
|
|
".".join(str(loc) for loc in error["loc"][1:])
|
|
for error in exc.errors()
|
|
]
|
|
|
|
problem = ProblemDetail(
|
|
type="https://api.example.com/errors/validation",
|
|
title="Validation Error",
|
|
status=422,
|
|
detail="The request contains invalid or missing fields",
|
|
instance=str(request.url.path),
|
|
extensions={
|
|
"trace_id": request.state.trace_id,
|
|
"invalid_fields": invalid_fields,
|
|
"errors": exc.errors()
|
|
}
|
|
)
|
|
|
|
return JSONResponse(
|
|
status_code=422,
|
|
content=problem.model_dump(exclude_none=True),
|
|
headers={"Content-Type": "application/problem+json"}
|
|
)</code></pre>
|
|
<h2>Error Internationalization</h2>
|
|
<h3>Multi-Language Errors</h3>
|
|
<p>Support error messages in multiple languages:</p>
|
|
<pre><code class="lang-python">from typing import Dict
|
|
from enum import Enum
|
|
|
|
class Language(str, Enum):
|
|
EN = "en"
|
|
ES = "es"
|
|
FR = "fr"
|
|
|
|
ERROR_MESSAGES: Dict[str, Dict[Language, str]] = {
|
|
"USER_NOT_FOUND": {
|
|
Language.EN: "User not found",
|
|
Language.ES: "Usuario no encontrado",
|
|
Language.FR: "Utilisateur non trouvรฉ"
|
|
},
|
|
"VALIDATION_ERROR": {
|
|
Language.EN: "Request validation failed",
|
|
Language.ES: "Error de validaciรณn de solicitud",
|
|
Language.FR: "รchec de validation de la demande"
|
|
},
|
|
"UNAUTHORIZED": {
|
|
Language.EN: "Authentication required",
|
|
Language.ES: "Autenticaciรณn requerida",
|
|
Language.FR: "Authentification requise"
|
|
}
|
|
}
|
|
|
|
def get_error_message(code: str, lang: Language = Language.EN) -> str:
|
|
"""Get localized error message"""
|
|
messages = ERROR_MESSAGES.get(code, {})
|
|
return messages.get(lang, messages.get(Language.EN, code))
|
|
|
|
@app.middleware("http")
|
|
async def add_language_context(request: Request, call_next):
|
|
# Extract language from header
|
|
accept_lang = request.headers.get("Accept-Language", "en")
|
|
lang = accept_lang.split(",")[0].split("-")[0].lower()
|
|
|
|
try:
|
|
request.state.language = Language(lang)
|
|
except ValueError:
|
|
request.state.language = Language.EN
|
|
|
|
return await call_next(request)
|
|
|
|
@app.exception_handler(HTTPException)
|
|
async def localized_http_exception_handler(
|
|
request: Request,
|
|
exc: HTTPException
|
|
):
|
|
lang = getattr(request.state, "language", Language.EN)
|
|
code = get_error_code_for_status(exc.status_code)
|
|
|
|
error_response = ErrorResponse.create(
|
|
code=code,
|
|
message=get_error_message(code, lang)
|
|
)
|
|
|
|
return JSONResponse(
|
|
status_code=exc.status_code,
|
|
content=error_response.model_dump()
|
|
)</code></pre>
|
|
<h2>Best Practices</h2>
|
|
<h3>Security Considerations</h3>
|
|
<p>Avoid leaking sensitive information:</p>
|
|
<pre><code class="lang-python"># โ BAD - Exposes internal details
|
|
@app.get("/users/{user_id}")
|
|
async def get_user(user_id: str):
|
|
try:
|
|
result = await db.execute(f"SELECT * FROM users WHERE id = {user_id}")
|
|
except Exception as e:
|
|
raise HTTPException(
|
|
status_code=500,
|
|
detail=f"Database error: {str(e)}" # Leaks SQL details!
|
|
)
|
|
|
|
# โ
GOOD - Generic error, detailed logging
|
|
@app.get("/users/{user_id}")
|
|
async def get_user(user_id: str, request: Request):
|
|
try:
|
|
result = await db.execute(query, user_id=user_id)
|
|
except Exception as e:
|
|
# Log full details
|
|
logger.exception("Database query failed", extra={
|
|
"trace_id": request.state.trace_id,
|
|
"query": query,
|
|
"user_id": user_id
|
|
})
|
|
|
|
# Return generic error
|
|
raise HTTPException(
|
|
status_code=500,
|
|
detail="An error occurred while retrieving user data"
|
|
)</code></pre>
|
|
<h3>Consistent Error Codes</h3>
|
|
<p>Define error codes consistently:</p>
|
|
<pre><code class="lang-python">class ErrorCode:
|
|
"""Centralized error code definitions"""
|
|
|
|
# Authentication & Authorization
|
|
UNAUTHORIZED = "UNAUTHORIZED"
|
|
INVALID_CREDENTIALS = "INVALID_CREDENTIALS"
|
|
TOKEN_EXPIRED = "TOKEN_EXPIRED"
|
|
FORBIDDEN = "FORBIDDEN"
|
|
|
|
# Resource Errors
|
|
NOT_FOUND = "NOT_FOUND"
|
|
ALREADY_EXISTS = "ALREADY_EXISTS"
|
|
CONFLICT = "CONFLICT"
|
|
|
|
# Validation Errors
|
|
VALIDATION_ERROR = "VALIDATION_ERROR"
|
|
INVALID_FORMAT = "INVALID_FORMAT"
|
|
MISSING_FIELD = "MISSING_FIELD"
|
|
|
|
# Rate Limiting
|
|
RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
|
|
|
|
# Server Errors
|
|
INTERNAL_ERROR = "INTERNAL_ERROR"
|
|
SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
|
|
DATABASE_ERROR = "DATABASE_ERROR"</code></pre>
|
|
<h3>Error Response Templates</h3>
|
|
<p>Create reusable error responses:</p>
|
|
<pre><code class="lang-python">class ErrorTemplates:
|
|
@staticmethod
|
|
def not_found(resource: str, identifier: str) -> APIError:
|
|
return APIError(
|
|
code=ErrorCode.NOT_FOUND,
|
|
user_message=f"{resource} not found",
|
|
dev_message=f"{resource} with id '{identifier}' does not exist",
|
|
status_code=404
|
|
)
|
|
|
|
@staticmethod
|
|
def already_exists(resource: str, field: str, value: str) -> APIError:
|
|
return APIError(
|
|
code=ErrorCode.ALREADY_EXISTS,
|
|
user_message=f"{resource} already exists",
|
|
dev_message=f"{resource} with {field}='{value}' already exists",
|
|
status_code=409
|
|
)
|
|
|
|
@staticmethod
|
|
def unauthorized(reason: Optional[str] = None) -> APIError:
|
|
return APIError(
|
|
code=ErrorCode.UNAUTHORIZED,
|
|
user_message="Authentication required",
|
|
dev_message=reason or "No valid authentication credentials",
|
|
status_code=401
|
|
)
|
|
|
|
# Usage
|
|
@app.get("/users/{user_id}")
|
|
async def get_user(user_id: str):
|
|
user = await db.get_user(user_id)
|
|
if not user:
|
|
raise ErrorTemplates.not_found("User", user_id)
|
|
return user
|
|
|
|
@app.post("/users")
|
|
async def create_user(user: UserCreate):
|
|
existing = await db.find_by_email(user.email)
|
|
if existing:
|
|
raise ErrorTemplates.already_exists("User", "email", user.email)
|
|
return await db.create_user(user)</code></pre>
|
|
<h2>Related Skills</h2>
|
|
<ul><li><strong>modal-web-endpoints.md</strong> - Error handling in Modal APIs</li><li><strong>ios-networking.md</strong> - Client-side error handling</li><li><strong>network-resilience-patterns.md</strong> - Retry and timeout patterns</li></ul>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/api-api-error-handling.md">This page as plain text</a> ยท <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |