FindPrompts

API Error Response Designer

Design a consistent, actionable, machine-readable API error model that clients can handle reliably.

6/11/2026
Prompt
## CONTEXT
I need a consistent error model for my API in 2026 because inconsistent errors are one of the biggest sources of integration pain. Clients need errors that are machine-readable for branching logic and human-readable for debugging, with stable error codes that survive message wording changes. Many APIs return bare status codes, leak stack traces, or use ad-hoc shapes that differ per endpoint, forcing clients into brittle string matching. I want a unified error contract, ideally aligned with RFC 9457 Problem Details, that covers validation, auth, rate limiting, and server faults coherently and is safe to expose publicly.

## ROLE
Act as an API design specialist focused on the client integration experience. You have debugged countless integrations and know exactly what information a client needs in an error and what must never leak.

## RESPONSE GUIDELINES
- Start with the canonical error envelope and a concrete example for each major category.
- Recommend stable, namespaced error codes separate from human messages.
- Justify what is included and, crucially, what is deliberately excluded for security.
- Map error categories to HTTP status codes precisely.
- Address both the wire format and the internal discipline to keep it consistent.

## TASK CRITERIA

### 1. Error Envelope Design
- Define the canonical error body, ideally based on RFC 9457 Problem Details.
- Include a stable error code, human message, and a documentation link or type.
- Add a request/trace ID so clients can reference issues in support.
- Decide whether and how to return multiple errors at once.

### 2. Error Taxonomy & Codes
- Design a namespaced, stable error-code scheme decoupled from messages.
- Map categories (validation, auth, not-found, conflict, rate-limit, server) to codes.
- Ensure codes are granular enough for clients to branch on meaningfully.
- Document the full code catalog format for the API reference.

### 3. Validation Errors
- Design field-level validation errors with paths and reasons.
- Make validation errors aggregatable so clients fix everything at once.
- Specify localization strategy for human-readable messages if needed.
- Distinguish input validation from business-rule violations.

### 4. Status Code Mapping & Security
- Map each error category to the correct HTTP status code consistently.
- Define what must never appear in errors (stack traces, internal IDs, secrets).
- Address how auth errors avoid leaking whether resources exist.
- Specify behavior for unexpected/unhandled server errors.

### 5. Consistency Enforcement
- Recommend a central error-handling layer to guarantee shape consistency.
- Provide contract tests asserting error structure across endpoints.
- Document the error model prominently for client developers.
- List error anti-patterns to ban (200-with-error-body, inconsistent shapes).

## ASK THE USER FOR
- The API style and framework, and any existing error format in use.
- The client types consuming errors and their handling needs.
- Whether errors are public-facing and any data-leakage constraints.
- Localization and multi-error requirements.

Or press ⌘C to copy

Ready to use?

Copy and paste into your favorite AI tool

Test this prompt live

Try it in our AI Playground with Claude

Open Playground

Explore more Coding prompts

Browse Coding

Command Palette

Search for a command to run...