Error Handling and Information Disclosure
What you'll learn: How to design API error responses that help developers debug without revealing sensitive system details to attackers.
The Security Dilemma of Error Messages
When your API encounters an error, you face a tricky balance: developers need useful information to fix problems, but detailed error messages can reveal your application's internals to attackers. Stack traces, database queries, file paths, and internal system details are gold mines for reconnaissance.
Think of it like a security guard at a building. When someone can't enter, saying "Your badge number doesn't exist in our database running MySQL 5.7 on server web-prod-03 at /var/www/api" is far more helpful to a burglar than simply saying "Access denied."
What Not to Expose
Never include in production error responses:
- Stack traces (reveal code structure and libraries)
- Database error messages (leak schema details)
- File system paths (expose server architecture)
- Software versions (help attackers find known vulnerabilities)
- Internal IP addresses or hostnames
- Detailed validation failures (enable enumeration attacks)
The Right Approach
For clients (production): Return generic, standardized error codes with minimal detail:
{
"error": "Authentication failed",
"code": "AUTH_ERROR"
}
For developers: Log complete error details server-side with correlation IDs:
{
"error": "Authentication failed",
"code": "AUTH_ERROR",
"trace_id": "a1b2c3d4"
}
Your server logs (never exposed) contain: [a1b2c3d4] SQLException: Invalid column 'usr_token' in table 'oauth_sessions'...
This way, legitimate developers can debug using trace IDs, while attackers only see generic messages.
Key Takeaway: Design error responses that are helpful through trace IDs and logging, not through exposing internal system details in the API response itself.