## Intro REST APIs are the backbone of modern web services, but when they fail, finding the root cause can be frustrating. This guide helps developers, DevOps engineers, and technical teams move from an observed error to a verified fix with practical, version-aware steps. We focus on common REST API errors in Node.js/Express applications with MongoDB, covering error messages, debugging techniques, and recovery procedures. The goal is operational safety: observe before changing, limit blast radius, use placeholders for secrets, verify results, and document recovery paths. Every command and configuration shown is illustrative; replace placeholders with your actual values. ## Version and Environment Inventory Before troubleshooting, know your environment. Identify the installed versions of Node.js, Express, and MongoDB, the deployment topology, and any relevant middleware. Use read-only commands to capture the current state. ### Observe Current State Run these commands on your server or development machine: node --version npm list express mongodb mongo --version Expected output example: v18.17.0 express@4.18.2 mongodb@5.7.0 MongoDB shell version v5.0.15 Record these versions. If you are using a process manager like PM2, check the running processes: pm2 list Look for the API service name and its status (online, errored). ### Define Expected Result and Failure Signal For any change, know what success looks like. For example, if you restart the API, the expected result is a successful startup with a log entry like "Server listening on port 3000". Failure signals include an exit code non-zero, a stack trace, or a timeout. ### Prerequisites and Blast Radius Before making changes, ensure you have: - SSH access or console access to the server. - Backup of configuration files (e.g., .env, config.js). - A rollback plan (e.g., previous version in version control or a snapshot). - Understanding of which clients are affected (e.g., all users or a subset). Never use real credentials in examples. Always use placeholders like or . ## Safe Configuration Path Many REST API errors stem from misconfiguration. Approach changes carefully. ### Common Configuration Issues - Incorrect database connection string. - Missing environment variables. - Wrong CORS settings. - Improper error-handling middleware. - Incorrect port binding. ### Example: Debugging a Database Connection Error Suppose your API returns 500 errors and logs show MongoNetworkError . Check your .env file for the MongoDB URI: cat .env Expected format: MONGODB_URI=mongodb+srv://:@cluster0.example.mongodb.net/?retryWrites=true&w=majority If the URI is missing or malformed, fix it. Use a placeholder for the password and never commit real secrets. Then restart your API: pm2 restart api Verify by checking logs: pm2 logs api --lines 20 Look for "Connected to MongoDB" or similar. If you see an authentication error, the username or password may be wrong. Test the connection with the MongoDB shell: mongosh "$MONGODB_URI" --eval 'db.runCommand({ ping: 1 })' Expected output: { ok: 1 } . If it fails, check credentials and network access. ### Blast Radius and Verification Changing the database URI affects the entire API. If you have multiple instances, you must update each. Verify after change with a health endpoint: curl -s http://localhost:3000/health Expected: {"status":"ok","database":"connected"} . ## Verification and Diagnostics After any fix, verify systematically. ### Health Endpoint Implement a health check endpoint that reports database connectivity and other dependencies. Example Express route: app.get('/health', async (req, res) => { try { await mongoose.connection.db.admin().ping(); res.json({ status: 'ok', database: 'connected' }); } catch (err) { res.status(503).json({ status: 'error', database: 'disconnected' }); } }); ### Request Logging and Tracing Use middleware like morgan for request logging: const morgan = require('morgan'); app.use(morgan('combined')); Logs will show request method, URL, status, and response time. For deeper tracing, use a correlation ID per request. ### Reproduce the Error Try to reproduce the error with curl or Postman. For a 404 error, check the route definition: curl -i http://localhost:3000/api/users/123 If you get 404, your route may not match. Verify in your Express app: app.get('/api/users/:id', getUser); Note the :id parameter. If you misspelled the path, fix it. ### Check API Documentation Use Swagger or OpenAPI to compare expected vs. actual endpoints. ## Failure Modes and Recovery Understand common failure modes and how to recover. ### Common REST API Errors and Fixes

Error Type	HTTP Status	Common Cause	Fix Example
Validation Error	400 Bad Request	Missing required field, invalid format	Use express-validator; return clear error messages.
Authentication Error	401 Unauthorized	Missing or invalid token	Check Authorization header; verify token with `jsonwebtoken`.
Authorization Error	403 Forbidden	Insufficient permissions	Check user role; ensure middleware grants access.
Not Found	404 Not Found	Wrong URL or resource missing	Verify route path and resource existence.
Conflict	409 Conflict	Duplicate resource	Check unique constraints; handle gracefully.
Server Error	500 Internal Server Error	Unhandled exception, database failure	Add error middleware; log stack; return generic message.
Service Unavailable	503 Service Unavailable	Overloaded, dependency down	Implement circuit breaker; scale horizontally.

### Recovery Procedures - 500 errors : Check logs for stack trace. Fix the bug, deploy, and restart. Use a process manager to auto-restart on crash. - Database connection failure : Verify network, credentials, and database status. Use mongosh to test. - Memory leaks : Monitor memory usage with node --inspect or clinic doctor . Restart with PM2 to recover, then fix the leak. - Rate limiting : If overwhelmed, add rate limiting middleware like express-rate-limit . ### Example: Fixing a 500 Error from Unhandled Rejection If you see UnhandledPromiseRejectionWarning , your async function lacks error handling. Add try-catch: app.get('/data', async (req, res, next) => { try { const data = await fetchData(); res.json(data); } catch (err) { next(err); // pass to error middleware } }); Then add a centralized error handler: app.use((err, req, res, next) => { console.error(err.stack); res.status(500).json({ error: 'Internal server error' }); }); ## Common Pitfalls and How to Avoid Them ### Ignoring Environment Variables Many developers hardcode configuration, leading to errors in different environments. Use a package like dotenv and keep sensitive data out of code. Why it happens : Convenience during development. How to avoid : Always load configuration from environment variables. Use .env.example templates. ### Poor Error Handling Not handling errors properly results in unhelpful responses and unknown failures. Implement global error middleware and validate inputs. Why it happens : Lack of planning or time pressure. How to avoid : Follow Express error handling best practices. Use async error wrappers or express-async-errors . ### Not Monitoring Logs Without logs, diagnosing errors is guesswork. Set up structured logging and monitor. Why it happens : Perceived as extra work. How to avoid : Use pino or winston for structured logs. Aggregate with tools like ELK or Datadog. ### Overlooking CORS CORS errors are common in browser-based clients. Configure CORS properly with cors middleware. Why it happens : Misunderstanding of same-origin policy. How to avoid : Explicitly set allowed origins, methods, and headers. ### Neglecting Database Indexes Slow queries can mimic errors. Use MongoDB explain to check query performance. Why it happens : Not testing with production-like data. How to avoid : Create indexes for frequent queries. ## Operations Checklist Before you start troubleshooting, go through this checklist. Assign an owner for each item and set a review cadence.

Checklist Item	Owner	Frequency	Verification
Verify current API version and dependencies	DevOps Engineer: Alex Chen	Weekly	`npm outdated`
Check server logs for errors	Backend Lead: Priya Shah	Daily	Log aggregation tool
Confirm database connectivity	Database Admin: Jordan Lee	Weekly	`mongosh ping`
Review error rates and latency	SRE: Sam Rivera	Daily	Monitoring dashboard
Test backup and recovery process	DevOps Engineer: Alex Chen	Monthly	Restore test
Review security headers and CORS	Security Engineer: Mia Wang	Monthly	Security scan
Validate environment variables	Backend Lead: Priya Shah	Weekly	`env-cmd --check`
Check API documentation accuracy	Tech Writer: Chris Johnson	Monthly	Swagger validation

This checklist ensures proactive health. The owners are accountable; review cadence catches issues before they become incidents. ## Conclusion Troubleshooting REST API errors requires a systematic approach: know your environment, observe before changing, make small, verifiable changes, and document recovery paths. By following the practices in this guide—version inventory, safe configuration, verification, and understanding failure modes—you can reduce downtime and improve reliability. Next step: pick one low-risk verification from the checklist, run it, record the result, and compare with expected output. Then review your error handling and monitoring to catch issues early. A reliable API makes failures visible, protects sensitive data, limits changes, and defines recovery before an incident occurs.