api error handling architect

    1

    Standardize API failure responses with consistent schemas, status codes, and security-first logging contracts.

    $5

    Secure checkout via Stripe

    30-day refund guarantee

    Converts to your local currency at checkout

    0 installsSecurity scanned

    Works with the AI tools you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIGitHub CopilotGitHub CopilotGemini CLIGemini CLI+20 more

    api error handling architect

    Example session with this skill installed

    Design an error handling contract for a new FinTech API. It needs to handle failed payments, invalid IBANs, expired sessions, and rate limits. Make sure it follows security best practices.

    • Read your context and instructions
    • Compiled the api error handling

    I have designed a consistent API error-handling contract for the FinTech API. This design ensures that payment failures are actionable, PII is protected, and all errors are traceable via correlation IDs.

    API Error Handling Contract

    1. Response Schema

    {
  "error": {
    "code": "PAYMENT_INSUFFICIENT_FUNDS",
    "message": "The transaction could not be completed. Please check your balance.",
    "target": "source_account_id",
    "details": [],
    "correlationId": "req-7b8c9d0a-1234",
    "retryable": false,
    "documentationUrl": "https://api.docs.fintech.com/errors/PAYMENT_INSUFFICIENT_FUNDS"
  }
}

    2. HTTP Status Map

    Failure ClassHTTP StatusMachine CodeRetryable
    Payment Declined402 Payment RequiredPAYMENT_DECLINEDNo
    Invalid IBAN422 Unprocessable EntityVALIDATION_IBAN_INVALIDNo
    Expired Session401 UnauthorizedAUTH_SESSION_EXPIREDNo (Re-auth)
    Rate Limited429 Too Many RequestsRATE_LIMIT_EXCEEDEDYes
    Internal Error500 Internal Server ErrorINTERNAL_SERVER_ERRORYes

    3. Headers & Logging

    Headers: All error responses must include X-Correlation-ID and Content-Type: application/problem+json. 429 errors must include Retry-After.

    • Logging: Log at ERROR level for 5xx and WARN for 4xx. Redact card_number, cvv, and iban from all logs.

    4. Test Matrix

    ClassTriggerAssertion
    AuthInvalid TokenStatus 401, Message is generic "Unauthorized"
    ValidationAlpha chars in IBANStatus 422, target is "iban", code is VALIDATION_IBAN_INVALID
    Security500 ErrorAssert body does not contain "Exception" or stack trace strings

    Next steps

    1. Review the machine-readable codes for alignment with your SDK naming conventions.
    2. Implement the X-Correlation-ID middleware in your gateway.
    3. Apply the PII denylist to your centralized logging configuration.

    Connects securely to your tools. The creator never sees your data.

    What you get

    Standardize error shapes across multiple microservices.Prevent internal data leaks in 500 error responses.Define retry logic and headers for client-side resilience.Create a testable contract for API failure modes.

    About this skill

    The problem

    Inconsistent API errors break client integrations and leak sensitive system details. Developers often waste hours debugging production failures because error responses lack correlation IDs, retry guidance, or stable machine-readable codes.

    What it does

    • Generates a unified JSON error envelope with machine-readable codes and safe messaging.
    • Maps failure modes to correct HTTP status codes including 401/403 distinctions and 422 for validation.
    • Defines a correlation ID contract for end-to-end request tracing across headers and logs.
    • Produces a retry semantics policy with Retry-After header logic for 429 and 503 errors.
    • Drafts a test matrix and logging contract with PII redaction rules and severity mapping.

    Why this beats prompting it yourself

    Generic prompts often miss security nuances, like leaking account existence through auth messages or exposing stack traces in 5xx responses. This skill enforces a strict six-axis validation (Security, Consistency, Debuggability, etc.) that ensures your error handling is production-ready, not just a simple JSON template.

    Use cases

    • Bootstrapping a new microservice architecture with a shared error contract.
    • Standardizing error shapes across multiple legacy services during a migration.
    • Designing public-facing API documentation that requires high debuggability for third-party developers.
    • Auditing an existing API to remove internal leaks and improve observability.

    Known limitations

    This skill produces a design contract and architectural documentation. it does not generate runtime middleware code or framework-specific handler implementations.

    How to install

    Works the same in every agent - Claude, Cursor, Codex, Copilot and 20+ more.

    ~30 seconds
    1. 1

      Download the ZIP

      Free skills download straight away. Paid skills unlock right after purchase.

    2. 2

      Unzip into your skills folder

      Every agent reads skills from one folder on your machine. Drop the unzipped folder in there.

    3. 3

      Ask your agent to use it

      Restart the agent if it was already running. It picks the skill up automatically - no config needed.

    Skills folder by agent

    Click the path to copy it. Create the folder if it does not exist yet.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill passes our trust checks below.

    Security scanned

    Passed our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    30-day refund

    Not a fit? Get your money back

    Trust & safety

    Security scanned

    Verified clean 9 days ago

    • Passed all security checks, Safe to install

    Listed9 days ago

    What's inside

    Frequently Asked Questions