Error-Handling Code Example Prompt Template

This prompt is for documentation engineers and DevRel teams who need to generate realistic, runnable code examples that demonstrate proper error handling for API calls. Use it when your documentation must show developers how to handle network failures, invalid responses, rate limits, and unexpected exceptions without swallowing errors silently. The ideal user already has a defined API contract and error schema—this prompt translates that contract into a complete, annotated code block that covers both expected error types (4xx, 5xx) and unexpected failures (network timeouts, DNS resolution), including retry logic where appropriate.

Do not use this prompt for generating happy-path-only examples, security-specific auth flows, or framework-specific middleware configuration. It is not designed for producing code that demonstrates a single successful API call without error branches, nor for generating OAuth token exchange logic or Express middleware error handlers. The prompt assumes the target API contract and error schema are already defined—if you are still designing the error response format or haven't finalized which status codes each endpoint returns, resolve those design decisions first. Similarly, if your documentation needs a complete SDK method reference or a full quickstart guide, pair this prompt with the SDK Quickstart or API Endpoint Usage Example prompts rather than overloading it.

Before using this prompt, gather the API endpoint specification, the error response schema for each status code, the retry policy (including backoff strategy and max attempts), and the target language and runtime version. The prompt works best when you provide concrete error payloads rather than abstract descriptions—real JSON error bodies produce more accurate catch blocks and conditional logic. After generation, validate the output by running the code against a mock server that returns each documented error type, and verify that no exception goes uncaught and that retry logic respects rate-limit headers. If the generated example will appear in production documentation, add a human review step to confirm the error-handling pattern matches your team's conventions and doesn't introduce resource leaks or infinite retry loops.

This prompt template is designed to generate a single, runnable code example that demonstrates robust error handling for a specific API endpoint. Unlike basic 'happy path' snippets, this prompt forces the model to produce code that accounts for real-world failure modes, including network issues, server errors, and client mistakes. The output is a complete, self-contained code block with inline comments, ready for a developer to copy, adapt, and integrate into a larger application. The template uses square-bracket placeholders that you must replace with your specific API details, target language, and error-handling requirements before use.

textCopy
Generate a complete, runnable code example in [LANGUAGE] that demonstrates robust error handling for calling the [API_ENDPOINT] endpoint using the [HTTP_CLIENT_OR_SDK] library. The example must cover the following error scenarios: [LIST_ERROR_SCENARIOS]. Include retry logic with exponential backoff and jitter for retryable errors [RETRYABLE_STATUS_CODES]. The code must never swallow exceptions silently. Every caught exception must either be logged with context, re-thrown with additional information, or handled with a documented fallback. Add inline comments explaining the purpose of each error handler. The output must be a single code block with no surrounding explanation. Use [LANGUAGE_VERSION]-idiomatic patterns and avoid deprecated APIs. The success response type is [SUCCESS_RESPONSE_TYPE] and the error response type is [ERROR_RESPONSE_TYPE]. [ADDITIONAL_CONSTRAINTS]

To adapt this template, start by replacing the core placeholders. For [LANGUAGE] and [LANGUAGE_VERSION], specify the exact target, such as Python and 3.11+. For [HTTP_CLIENT_OR_SDK], choose the specific library, like httpx or the openai Python SDK. The [LIST_ERROR_SCENARIOS] placeholder is critical; be explicit, for example: a 401 authentication error, a 429 rate limit with a Retry-After header, a 503 server error, and a network timeout. Define [RETRYABLE_STATUS_CODES] as a list like [429, 503]. The [SUCCESS_RESPONSE_TYPE] and [ERROR_RESPONSE_TYPE] placeholders should be filled with concrete types or structures, such as dict or MyAPIError. Use the [ADDITIONAL_CONSTRAINTS] field to enforce project-specific rules, like 'Do not use third-party retry libraries' or 'Use structured logging with structlog'. After generating the code, always validate it against your project's linting, security scanning, and testing harness before publishing it in documentation.

Wire this prompt into a documentation generation pipeline by calling it once per endpoint per language. Store the output as a raw code block in your documentation CMS. The prompt expects [API_OPERATION], [LANGUAGE], [SDK_CLIENT], [ERROR_CATALOG], and [ADDITIONAL_CONSTRAINTS] as inputs. Map these from your API spec, error code registry, and style guide before each invocation. For teams using OpenAPI, extract the operation ID, response schemas, and documented error codes programmatically to populate [ERROR_CATALOG] with the exact error shapes your API returns—don't let the model invent error types.

Before publishing, run the generated code through a syntax validator for the target language. Use pylint --errors-only for Python, ruby -c for Ruby, node --check for JavaScript, or the equivalent compiler/linter for your language. If the code references a real SDK, execute it against a mock server that returns both success and error responses to verify the error branches are reachable. The mock server must simulate at minimum: a 4xx client error with a structured error body, a 5xx server error, and a network timeout. Assert that the generated example catches each error type without swallowing exceptions silently and that retry logic (if present) respects the mock's Retry-After headers. Log every generated example with its prompt variables—operation ID, language, SDK version, and timestamp—for traceability when examples later break.

For high-risk APIs where incorrect error handling could cause data loss (write operations, deletion endpoints, financial transactions), require a human reviewer to approve the example before publication. Set a max token limit of 1500 for the output to prevent the model from generating overly verbose examples that bury the error-handling logic in boilerplate. If the output fails syntax validation, retry once with the error message appended to [ADDITIONAL_CONSTRAINTS]—for example, [ADDITIONAL_CONSTRAINTS]: Previous output failed Python syntax check: 'SyntaxError: invalid syntax at line 12'. Fix the syntax error while preserving the error-handling logic. If the retry also fails, flag the example for manual authoring and log the failure pattern to improve the prompt template over time.