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
#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" } }