Design consistent API error responses developers can act on
Turns unhelpful API errors into a consistent format with clear codes, statuses, and messages that tell callers exactly what to fix.
The prompt
Help me design consistent, actionable error responses for my API.
Current errors: [PASTE EXAMPLE ERROR RESPONSES, CODES, OR THE CODE THAT THROWS THEM]
API style: [REST / GraphQL / gRPC - and any existing error format]
Who calls the API: [INTERNAL FRONTEND / PARTNER INTEGRATIONS / PUBLIC DEVELOPERS]
Constraints: [e.g. "must not reveal whether an email is registered", "existing clients parse the 'message' field", "localized UI messages"]
Steps:
1. Audit each current error: is the status code right, can a program branch on it, does a human know what to fix, and is anything leaked?
2. Flag security problems: stack traces, internal hostnames, SQL, library versions, or responses that allow account or resource enumeration (e.g. different errors for "wrong password" vs. "no such user").
3. Propose one error format (e.g. RFC 9457 Problem Details for HTTP APIs, or my existing convention) with: a stable machine-readable error code, a short human message, field-level details for validation errors, a request or correlation ID, and a docs link placeholder [DOCS LINK].
4. Rewrite each error. The message must name the problem, the offending field or parameter, and the expected format or valid values.
5. Separate what goes in the response from what goes only in logs (full detail and correlation ID, never secrets or personal data).
6. Note retry guidance: which errors are safe to retry, and when to send Retry-After.
Return:
- An audit table (original, problem, new code, HTTP status, rewritten message, retryable?).
- The error format spec with one validation and one server-error example.
- A backward-compatibility note if existing clients may break, with a migration approach.
- 5 rules for my team's API style guide.
Highlighted [brackets] are blanks to replace with your own details.
Fill in the blanks and use this promptMore Software Development prompts
What to fill in
- REST / GraphQL / gRPC - and any existing error format
- INTERNAL FRONTEND / PARTNER INTEGRATIONS / PUBLIC DEVELOPERS
- DOCS LINK
How this prompt is built
This prompt follows the Few-Shot structure (Few-shot prompting). A few-shot prompt includes one or more worked examples of the input and the output you want, so the model can copy the pattern instead of guessing it.
Related prompts
- Reply to code review comments I disagree withDrafts calm, evidence-based replies to review feedback so you can resolve disagreements without stalling the pull request.
- Diagnose slow launches and API cold starts in my mobile appA codebase-specific diagnosis of startup time, serverless cold starts, and network waste, with fixes ranked by impact on perceived speed.
- Set up experiment tracking for a machine learning training runStep-by-step setup to log metrics, hyperparameters, and artifacts from your training script, locally or on a cluster.
- Diagnose and fix a flaky testWorks out why a test passes and fails intermittently, how to reproduce it, and how to fix the cause rather than adding retries.