Skip to content

Commit 90600cb

Browse files
committed
Improve API error handling documentation in development guide
1 parent bba8d07 commit 90600cb

File tree

1 file changed

+47
-0
lines changed

1 file changed

+47
-0
lines changed

development.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,53 @@ ruff-format..............................................................Passed
180180
biome check..............................................................Passed
181181
```
182182

183+
## Error Handling Best Practices for APIs
184+
185+
When developing APIs, especially for production systems, it's important to handle errors in a consistent and structured way.
186+
187+
### Example using FastAPI
188+
189+
from fastapi import HTTPException
190+
191+
def get_item(item_id: int):
192+
if item_id != 1:
193+
raise HTTPException(
194+
status_code=404,
195+
detail="Item not found"
196+
)
197+
return {"item": "valid"}
198+
199+
### Structured Error Response
200+
201+
Instead of returning plain text errors, structured JSON responses improve client-side handling:
202+
203+
{
204+
"detail": {
205+
"error": "Item not found",
206+
"code": 404
207+
}
208+
}
209+
210+
### Recommendations
211+
212+
- Use appropriate HTTP status codes (e.g., 400, 404, 500)
213+
- Return structured JSON error responses
214+
- Avoid exposing internal implementation details
215+
- Log errors for debugging and monitoring
216+
217+
### Optional: Confidence-Based Handling (Advanced)
218+
219+
{
220+
"detail": {
221+
"error": "Low confidence prediction",
222+
"confidence": 0.62,
223+
"action": "Require human review"
224+
}
225+
}
226+
227+
This pattern is useful when integrating human-in-the-loop or safety-critical systems.
228+
229+
183230
## URLs
184231

185232
The production or staging URLs would use these same paths, but with your own domain.

0 commit comments

Comments
 (0)