Design Standardized REST API Error Contracts Using RFC 7807

Generate a comprehensive, machine-readable API error schema that follows the RFC 7807 Problem Details standard for consistent, client-side error handling.

Prompt

Prompt
You are a Senior Backend Architect. Your job is to design a standardized REST API error contract based on RFC 7807. Before generating the schema, ask these 3 questions: 1. What is the base URL or domain for your API? 2. What specific programming language or framework are you using? 3. Do you need to include internal tracking IDs or custom extension fields in the error response? After I answer, provide the design. Rules: 1. Every error response must include type, title, status, detail, and instance fields. 2. Define a custom error code system that maps to these HTTP status codes: 400, 401, 404, 409, and 422. 3. Provide a JSON Schema specification for the error object. 4. Provide one example JSON response for each of the 5 status codes. Output format: 1. Overview of the error strategy. 2. JSON Schema block. 3. Examples table with columns: HTTP Status, Error Code, Example JSON. This is for technical reference only; verify all security implications with your security team.

Example output

Example for: A Node.js Express API using a custom internal error code system for a banking application.

Error Strategy Overview

This design implements RFC 7807 to provide clients with predictable, machine-readable error responses. Each error includes a standard HTTP status code and a custom application-level error code to distinguish between specific business rule violations (e.g., insufficient funds vs. invalid account format).

JSON Schema
{
  "type": "object",
  "properties": {
    "type": { "type": "string", "format": "uri" },
    "title": { "type": "string" },
    "status": { "type": "integer" },
    "detail": { "type": "string" },
    "instance": { "type": "string", "format": "uri" },
    "code": { "type": "string" }
  },
  "required": ["type", "title", "status", "detail", "code"]
}
Error Response Examples
HTTP StatusError CodeExample JSON
400INVALID_PAYLOAD{"type": "/errors/bad-request", "title": "Invalid Input", "status": 400, "detail": "Field 'amount' must be a positive integer", "code": "INVALID_PAYLOAD"}
401UNAUTHORIZED{"type": "/errors/unauthorized", "title": "Missing Token", "status": 401, "detail": "Authorization header is missing", "code": "UNAUTHORIZED"}
404NOT_FOUND{"type": "/errors/not-found", "title": "Account Missing", "status": 404, "detail": "Account ID 123 not found", "code": "NOT_FOUND"}
409CONFLICT{"type": "/errors/conflict", "title": "Duplicate Transaction", "status": 409, "detail": "Transaction ID already processed", "code": "DUPLICATE_TX"}
422VALIDATION_ERR{"type": "/errors/validation", "title": "Validation Failed", "status": 422, "detail": "Insufficient balance for transfer", "code": "INSUFFICIENT_FUNDS"}
Written by AI from this prompt. Your results will vary.

Tips and common edits

Why this works

  • Forces adherence to the RFC 7807 standard for industry-wide compatibility.
  • Requires specific JSON schema and table-based examples for developer clarity.
  • Uses a mandatory question phase to customize the output to your stack.

Use this prompt when building new APIs to ensure consistent error handling across your microservices. Works perfectly in ChatGPT, Claude, or Gemini to generate documentation for your developers.

Common edits

  • Add a 'traceId' field to the schema to help with debugging production logs.
  • Adjust the error codes to match your existing domain-specific naming conventions.

Make it repeatable

Keep using this prompt without pasting it in every time.

Keep exploring

More in Coding