Back to prompts
Coding & Developmentintermediate
0.0

Write API Error Messages That Actually Help Developers

Bad error messages cost hours of debugging. This prompt creates clear, actionable error messages for every API endpoint.

Copy & Paste this prompt
You are a developer experience (DX) specialist who designs API error messages. You believe every error message should contain three things: what went wrong, why it went wrong, and how to fix it.

Design comprehensive error messages for my API.

API description: [DESCRIBE YOUR API — what it does, main resources]
Endpoints to cover: [LIST YOUR MAIN ENDPOINTS, or say 'all CRUD operations']
Auth method: [API KEY / JWT / OAUTH / NONE]
Common user mistakes: [WHAT DO DEVELOPERS GET WRONG MOST?]

For each endpoint, generate:

1. ERROR CATALOG — Every possible error with:
   - HTTP status code (correct usage — no 200 for errors!)
   - Error code (machine-readable, e.g., 'INVALID_FIELD_FORMAT')
   - Message (human-readable, includes WHAT happened)
   - Detail (WHY it happened)
   - Fix (HOW to resolve it — include example of correct usage)
   - Documentation link placeholder

2. VALIDATION ERRORS — Detailed field-level errors:
   { "error": "VALIDATION_ERROR", "message": "Request validation failed", "details": [{ "field": "email", "issue": "Invalid format", "expected": "user@domain.com", "received": "not-an-email" }] }

3. RATE LIMIT MESSAGE — With retry-after header and helpful context

4. AUTH ERRORS — Distinguish between: no token, expired token, invalid token, insufficient permissions

5. ERROR RESPONSE CONSISTENCY — A single error envelope format used everywhere
Use as Template
#api-design#developer-experience#error-messages#dx

Works with

chatgptclaudecopilot

💡 Pro Tips

  • •Never return just 'Bad request' or 'Internal server error' — always explain what went wrong
  • •Include the actual invalid value in the error (helps debugging immensely)
  • •Use consistent error codes across your entire API

✨ Example Output

Endpoint: POST /api/users
❌ BAD: { "error": "Bad request" }
✅ GOOD: { "error": { "code": "INVALID_FIELD_FORMAT", "message": "The 'email' field is not a valid email address", "detail": "Received 'john@' — email must include a domain (e.g., john@example.com)", "fix": "Provide a complete email address in the 'email' field", "docs": "https://api.example.com/docs/errors#INVALID_FIELD_FORMAT" } }

🧠 Why This Works

Most API error messages tell developers something went wrong without helping them fix it. This prompt designs error responses with machine-readable codes, human-readable explanations, and actionable next steps—reducing support tickets and improving developer experience.

📅 When to Use This Prompt

Use when designing error responses for a new API, when developer feedback says your error messages are confusing, or when you want to build a consistent error response format that helps API consumers debug issues independently.

🎯 What You'll Get

You'll get a complete error response specification with error code taxonomy, HTTP status mapping, message templates with context variables, documentation links, and examples showing how each error type guides developers toward resolution.

🔗 Related Prompts

Coding & DevelopmentPremium

RESTful API Design Architect

Design a complete, production-ready API from scratch — endpoints, auth, error handling, versioning, and documentation.

api-designrestbackend
★4.8
advanced
Coding & DevelopmentPremium

Error Message Humanizer

Transform cryptic error messages into user-friendly explanations and fixes.

debuggingerrorsdeveloper-experience
★4.5
beginner