API Error Classification Prompt for Agents

This prompt is for reliability engineers and agent developers who need to turn raw, provider-specific error outputs from REST and gRPC tools into a single, agent-actionable error taxonomy. The job-to-be-done is normalization: an agent receives a 502, a gRPC UNAVAILABLE, or a malformed JSON body from an upstream API, and without a standard classification, the agent's next action—retry, fallback, escalate, abort—is a guess. This prompt takes the raw error context and maps it to a known set of error categories so that downstream retry and fallback logic can operate on clean, predictable signals instead of brittle string matching.

Use this prompt when your agent orchestrates multiple API-backed tools and you need a single classification layer before any retry or circuit-breaker decision. It is designed for production tool-calling loops where errors arrive in inconsistent shapes: HTTP status codes, gRPC status enums, cloud provider error objects (e.g., AWS, GCP, Azure), or custom gateway error bodies. The prompt expects a structured input containing the raw error payload, the tool name, and the call context, and it outputs a classification object with a standard error category, a confidence score, and a concise reason. Do not use this prompt for user-facing error translation or for deciding what to do about the error—it only classifies. Pair it with the Retry Decision Prompt or Fallback Tool Selection Prompt to act on the classification.

Before deploying, you must test this prompt against your actual provider error formats. Common failure modes include misclassifying a provider's custom rate-limit header as a generic server error, or treating an authentication failure as a transient network issue. Build an eval set from your production error logs, and require human review of the classification mapping before wiring it into automated retry loops. If your agent operates in a regulated domain where incorrect retries could cause duplicate transactions or data loss, ensure the classification output is logged as part of the audit trail and that a human-in-the-loop gate exists for UNKNOWN or low-confidence classifications.

This prompt template is the core classification engine for an agent's error-handling pipeline. It takes a raw error payload—whether a JSON error body from a REST API, a gRPC status object, or a provider-specific error format—and maps it to a standard taxonomy that downstream retry, fallback, and escalation prompts can consume without parsing provider-specific details. The template is designed to be wrapped in a validation harness that checks for missing fields, hallucinated error codes, and incorrect severity assignments before the classification reaches any decision-making prompt.

textCopy
You are an API error classifier for a production agent system. Your job is to parse raw error output from an external tool call and produce a structured classification that downstream retry, fallback, and escalation prompts can act on.

## INPUT
Raw error payload:
[ERROR_PAYLOAD]

Tool context:
- Tool name: [TOOL_NAME]
- HTTP method: [HTTP_METHOD]
- Endpoint: [ENDPOINT]
- Request timestamp: [TIMESTAMP]

## TAXONOMY
Classify the error into exactly one of these categories:
- TRANSIENT_NETWORK: Connection refused, DNS failure, TCP reset, TLS handshake failure.
- TIMEOUT: Request exceeded deadline, upstream timed out.
- RATE_LIMITED: HTTP 429, quota exceeded, throttling response.
- AUTHENTICATION: HTTP 401, expired token, invalid credentials.
- AUTHORIZATION: HTTP 403, insufficient permissions, scope mismatch.
- INVALID_ARGUMENT: HTTP 400, 422, schema validation failure, missing required field.
- NOT_FOUND: HTTP 404, resource does not exist.
- CONFLICT: HTTP 409, resource version mismatch, duplicate.
- SERVER_ERROR: HTTP 5xx, internal upstream failure.
- SERVICE_UNAVAILABLE: HTTP 503, upstream in maintenance, overloaded.
- DEPENDENCY_FAILURE: Upstream dependency returned an error that propagated.
- UNKNOWN: Does not match any category above.

## OUTPUT SCHEMA
Return ONLY valid JSON matching this schema:
{
  "classification": "<category from TAXONOMY>",
  "severity": "critical|degraded|warning|transient",
  "is_retryable": true|false,
  "retry_reasoning": "<one sentence explaining why retry is or is not appropriate>",
  "provider_error_code": "<the original error code or status string from the provider>",
  "provider_error_message": "<the original error message, truncated to 500 chars>",
  "rate_limit_info": {
    "retry_after_seconds": <integer or null>,
    "quota_remaining": <integer or null>
  },
  "requires_human_review": true|false,
  "human_review_reason": "<one sentence if requires_human_review is true, otherwise null>",
  "partial_result_available": true|false,
  "partial_result_description": "<description if partial_result_available is true, otherwise null>"
}

## CONSTRAINTS
- Do not invent error codes. Use only what appears in the raw payload.
- If the error payload is empty or unparseable, set classification to UNKNOWN and severity to warning.
- Set requires_human_review to true for any AUTHENTICATION or AUTHORIZATION failure that mentions credential expiry, revoked access, or scope changes.
- Set severity to critical for any SERVER_ERROR or SERVICE_UNAVAILABLE that affects a write operation (POST, PUT, PATCH, DELETE).
- Set severity to transient for TIMEOUT and TRANSIENT_NETWORK.
- Extract retry_after_seconds from Retry-After headers or provider-specific rate-limit fields when present.
- If the error body contains partial results (e.g., a batch endpoint that processed some items before failing), set partial_result_available to true and describe what was completed.
- Do not include the raw error payload in your output.

To adapt this template, replace the taxonomy categories with your organization's standard error classification scheme if one exists. The severity and retryability logic in the CONSTRAINTS section should be tuned to your specific risk tolerance—for example, you may want all write-operation failures to require human review regardless of error type. The OUTPUT SCHEMA can be extended with fields like affected_entities, idempotency_key, or recommended_fallback_tool if your downstream prompts consume them. Before deploying, run this prompt through a validation harness that confirms every required field is present, classification matches one of the allowed enum values, and severity is consistent with the declared rules.

This prompt is designed to sit directly in the agent's error-handling path, immediately after a tool call returns a non-2xx HTTP status or a non-OK gRPC status. The agent's orchestrator should catch the raw error object—including the status code, response headers, and response body—and inject it into the [RAW_ERROR] placeholder. The prompt's structured output then becomes the single source of truth for all downstream decisions: whether to retry, fall back, escalate, or abort. Do not pass the raw error string directly to a retry or fallback prompt; the classification step prevents brittle string matching and ensures consistent decision-making across heterogeneous APIs.

Wire the prompt into a dedicated classify_api_error function within your agent's tool execution layer. This function should accept the raw error payload, call the LLM with the classification prompt, and parse the JSON response into a typed error object. Implement a strict output validator that checks for the required fields (error_category, is_retryable, retry_strategy, user_facing_message, severity) and rejects malformed responses. If validation fails, retry the classification call once; if it fails again, default to error_category: "UNKNOWN", is_retryable: false, and severity: "CRITICAL" to force safe escalation. Log every classification result—including the raw error, the classified output, and the validator result—as a structured event for later trace analysis and retry-storm detection.

For model choice, a fast, low-cost model like gpt-4o-mini or claude-3-haiku is sufficient for this classification task, as it requires pattern matching against HTTP/gRPC semantics rather than deep reasoning. Set temperature=0 to maximize output consistency. If your agent uses many provider-specific APIs (Stripe, AWS, Twilio), maintain a provider error registry—a small JSON map of known provider error codes to your standard taxonomy—and pass it into the [PROVIDER_ERROR_MAP] placeholder. This grounds the model in your specific API surface and reduces misclassification of opaque, provider-specific error codes. Do not rely on the model's parametric knowledge of third-party APIs; it will hallucinate error meanings for obscure or versioned endpoints.

The most common production failure mode is silent misclassification of 5xx errors as non-retryable. Always include an eval that tests a sample of 502, 503, and 504 responses against your provider map to confirm they are classified as TRANSIENT_SERVICE_ERROR with is_retryable: true. A second failure mode is information leakage into user-facing messages: the user_facing_message field must never contain stack traces, internal IPs, or raw error bodies. Add a post-classification sanitizer that scans the generated message for patterns like file paths, IP addresses, and stack trace signatures, and replaces the message with a safe fallback if any are detected. Finally, if the agent is operating in a regulated domain, route all CRITICAL severity classifications to a human review queue before any automated fallback or abort action is executed.