api error handling architect
Standardize API failure responses with consistent schemas, status codes, and security-first logging contracts.
$5
Works with the AI Agents you already use
Claude Code
Cursor
Codex CLI
Muse
Dots+21 moreClaude CodeCursorCodex CLIMuseDots
Manus
Grok
Grok Bot+18 agentsapi 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 Class | HTTP Status | Machine Code | Retryable |
|---|---|---|---|
| Payment Declined | 402 Payment Required | PAYMENT_DECLINED | No |
| Invalid IBAN | 422 Unprocessable Entity | VALIDATION_IBAN_INVALID | No |
| Expired Session | 401 Unauthorized | AUTH_SESSION_EXPIRED | No (Re-auth) |
| Rate Limited | 429 Too Many Requests | RATE_LIMIT_EXCEEDED | Yes |
| Internal Error | 500 Internal Server Error | INTERNAL_SERVER_ERROR | Yes |
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
ERRORlevel for 5xx andWARNfor 4xx. Redactcard_number,cvv, andibanfrom all logs.
4. Test Matrix
| Class | Trigger | Assertion |
|---|---|---|
| Auth | Invalid Token | Status 401, Message is generic "Unauthorized" |
| Validation | Alpha chars in IBAN | Status 422, target is "iban", code is VALIDATION_IBAN_INVALID |
| Security | 500 Error | Assert body does not contain "Exception" or stack trace strings |
Next steps
- Review the machine-readable codes for alignment with your SDK naming conventions.
- Implement the
X-Correlation-IDmiddleware in your gateway. - Apply the PII denylist to your centralized logging configuration.
Connects securely to your tools. The creator never sees your data.
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-Afterheader 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.
Produces design documentation and contracts only. Does not generate runtime code, middleware, or specific handler implementations for your web framework.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 1 month ago
Permissions
No special permissions declared or detected