Error Response Schema Design Prompt

Use this prompt when you are a backend engineer or platform developer responsible for defining the structured error outputs that an AI model will receive after a tool call fails. The job-to-be-done is not just writing an error message, but designing a machine-readable contract—a JSON schema for error responses—that enables the model to correctly interpret what went wrong, decide whether to retry, select a fallback tool, or escalate to a human. This prompt is ideal when you are building an AI agent, copilot, or any system where a model orchestrates external API calls and must recover gracefully from failures such as timeouts, validation errors, permission denials, or rate limits. The required context includes your tool's operational failure modes, the retry and idempotency characteristics of your endpoints, and the downstream user experience you need to protect.

Do not use this prompt if you are only designing user-facing error messages for a traditional web application with no AI intermediary. This prompt is specifically for the contract between your system and the model. It is also inappropriate if you are in the earliest prototyping phase and haven't yet identified the common failure modes of your tool; the output will be speculative and may lead to brittle recovery logic. The prompt assumes you can enumerate concrete error categories (e.g., TEMPORARY_SERVER_ERROR, INVALID_ARGUMENT, PERMISSION_DENIED) and that you have a clear policy on retries and human escalation. If your tool's side effects are not well-understood, start with the Side-Effect Documentation Prompt for Tools first.

Before running this prompt, gather your tool's existing error codes, HTTP status mappings, and any retry-after headers or idempotency keys you support. The output will be a complete error schema with codes, retry hints, and user-facing message templates, but its real value is in the evaluation harness: you will test whether the model, upon receiving each error type, chooses the correct recovery action. After generating the schema, you must integrate it into your tool's OpenAPI or function definition and run the provided eval cases. Avoid the temptation to hand-wave error handling; a model that misinterprets a 500 as a permanent failure when it should retry will silently degrade your product.

This prompt template is designed to produce a machine-readable error schema for a given API endpoint or tool. It forces the model to define error codes, retry hints, and user-facing message templates, creating a contract that your application and the AI can both rely on. Use this when you are defining the error surface of a new tool or auditing an existing one for gaps in recoverability.

textCopy
You are an API design expert. Your task is to produce a structured error response schema for the tool or endpoint described below. The schema must be interpretable by another AI model to decide whether to retry, ask the user for clarification, or fail permanently.

[TOOL_DESCRIPTION]

Generate a JSON object that conforms to the following [OUTPUT_SCHEMA]:
{
  "error_responses": [
    {
      "error_code": "STRING_IDENTIFIER",
      "http_status": 400,
      "condition": "Description of what triggers this error.",
      "retry_strategy": "no_retry | retry_with_backoff | retry_with_modified_args | ask_user",
      "retry_hint": "A brief instruction for the calling AI on how to modify its request.",
      "user_message_template": "A human-readable message with a [VARIABLE] placeholder.",
      "log_level": "ERROR | WARN"
    }
  ]
}

[CONSTRAINTS]
- Include at least one error for invalid input, one for a server-side failure, and one for a permission or rate-limit issue.
- The `retry_hint` must be a direct instruction to the AI, not the end user.
- The `user_message_template` must not expose internal system paths or stack traces.
- If the tool has a [RISK_LEVEL] of 'high', include an error for a required human approval step.

To adapt this template, replace [TOOL_DESCRIPTION] with a clear, plain-text description of what your API endpoint or tool does, including its side effects. The [OUTPUT_SCHEMA] can be extended with additional fields like error_category for analytics, but avoid removing the retry_strategy and retry_hint fields, as they are critical for downstream AI recovery logic. The [CONSTRAINTS] section is your policy lever; add rules here for compliance, security, or domain-specific error masking. After generating the schema, you must validate it against real failure modes by running the evaluation harness described in the testing section of this playbook.

The error response schema design prompt is not a one-off query—it is a schema generation step in a larger tool-authoring workflow. In practice, you will call this prompt whenever a new API endpoint is being exposed as a tool, or when an existing tool's error contract changes. The prompt expects a [TOOL_NAME], [TOOL_DESCRIPTION], and a list of [FAILURE_MODES] as input. The output is a structured error schema (typically JSON Schema) that defines error codes, retry hints, and user-facing message templates. This schema becomes part of the tool's output contract, consumed by the orchestration layer and by downstream recovery prompts.

Wire the prompt into your tool-registration pipeline as a pre-commit or CI step. After generating the error schema, run it through a JSON Schema validator to confirm structural correctness. Then execute a set of eval harness tests that simulate the model receiving each defined error type. For each error code, verify that the model's subsequent behavior matches the retry hint: for example, a TEMPORARY error should trigger a retry with backoff, while a PERMANENT error should cause the model to escalate or ask the user for clarification. Log the model's recovery action and compare it against expected behavior. If the model ignores the retry hint or retries a permanent error, flag the schema for revision. This eval loop is critical because a well-structured error schema is useless if the model cannot interpret it correctly under production conditions.

For high-risk tools—those that mutate state, send communications, or access sensitive data—add a human review gate before the error schema is deployed. The review should confirm that error codes are unambiguous, that retry hints do not cause infinite loops, and that user-facing message templates do not leak internal system details. Store the approved schema in a versioned registry alongside the tool definition. When the tool is called at runtime, the orchestration layer should parse the error response against this schema, validate it, and then feed the structured error back to the model for recovery. Avoid the temptation to let the model generate ad-hoc error interpretations; the schema is the contract, and the model's job is to follow it.