Error Handling

Complete guide to API error responses, status codes, and common issues.

📋 Error Response Format

All errors follow a consistent JSON structure:

{
  "success": false,
  "error": "Error message",
  "details": {
    "field": ["Validation error message"]
  },
  "statusCode": 400
}

🔢 HTTP Status Codes

Code	Meaning	When Used
200	OK	Successful GET, PUT
201	Created	Successful POST
400	Bad Request	Validation errors
401	Unauthorized	Missing/invalid authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Duplicate resource
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

⚠️ Common Errors

Authentication Errors

401 Unauthorized:

{
  "success": false,
  "error": "Authentication required",
  "statusCode": 401
}

Causes:

Missing Authorization header
Invalid or expired token
Malformed token

Solution:

Include valid access token
Refresh token if expired
Sign in again if refresh fails

Validation Errors

400 Bad Request:

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "email": ["Invalid email format"],
    "password": ["Password must be at least 6 characters"]
  },
  "statusCode": 400
}

Common validation issues:

Empty required fields
Invalid email format
Password too short
Invalid data types

Rate Limiting

429 Too Many Requests:

{
  "success": false,
  "error": "Too many requests. Please try again later.",
  "retryAfter": 900,
  "statusCode": 429
}

Rate limits:

Authentication: 10/min per IP
Feedback: 5/15min per IP
General API: 100/15min per IP

Server Errors

500 Internal Server Error:

{
  "success": false,
  "error": "Internal server error",
  "requestId": "req_abc123",
  "statusCode": 500
}

If you encounter this:

Check API status
Retry request
Contact support with requestId

🐛 Debugging

Enable Debug Mode

Set environment variable:

DEBUG=express:* pnpm dev

Check Logs

# View all logs
tail -f logs/combined.log

# View errors only
tail -f logs/error.log

Test Endpoints

# Health check
curl http://localhost:3001/health

# Admin health (detailed)
curl http://localhost:3001/api/admin/health \
  -H "Authorization: Bearer YOUR_TOKEN"

On this page