api-error-contract-designer
Skill1 starsChanged 5 days agoMITView on GitHub
Design or normalize an API's error contract so clients get stable machine-readable codes, safe human messages, field-level validation details, correlation IDs, and consistent HTTP semantics. Use when adding endpoints, replacing ad hoc error strings, documenting SDK behavior, or fixing clients that branch on fragile message text.
In this repository163 other files it gives its agents.
- agents.mdAGENTS.md
- 3d-asset-handoff-sheetSkill
- accessibility-regression-auditorSkill
- adr-writerSkill
- agent-memory-designerSkill
- agent-trajectory-evaluatorSkill
- alerting-rules-tunerSkill
- analysis-memo-writerSkill
- annotation-disagreement-ledgerSkill
- annotation-task-spec-builderSkill
- api-deprecation-plannerSkill
- architecture-diagram-generatorSkill
- asset-metadata-review-ledgerSkill
- auth-flow-reviewerSkill
- background-job-reliability-auditorSkill
- branch-rebaserSkill
- brand-voice-profilerSkill
- bundle-analyzerSkill
- cache-policy-designerSkill
- canary-release-plannerSkill
- caption-correction-ledgerSkill
- changelog-from-prsSkill
- chart-chooserSkill
- chunking-strategy-optimizerSkill
- circular-dependency-breakerSkill
- claude-settings-auditorSkill
- code-example-verifierSkill
- cold-email-deliverability-auditorSkill
- cold-start-optimizerSkill
- commit-splitterSkill
- competitor-teardownSkill
- component-spec-writerSkill
- connection-pool-tunerSkill
- content-repurposerSkill
- contract-obligation-registerSkill
- contract-test-designerSkill
- conventional-commitsSkill
- cors-configuratorSkill
- coverage-gap-finderSkill
- crm-export-auditorSkill
- dashboard-designerSkill
- data-retention-auditorSkill
- dataset-first-lookSkill
- dead-code-finderSkill
- deadlock-diagnoserSkill
- decision-log-reconcilerSkill
- dependency-auditSkill
- dependency-upgrade-plannerSkill
- design-brief-writerSkill
- design-critique-checklistSkill
- design-token-extractorSkill
- devcontainer-designerSkill
- distributed-tracing-instrumenterSkill
- dockerfile-optimizerSkill
- email-sequence-drafterSkill
- embedding-index-tunerSkill
- embedding-set-inspectorSkill
- entity-match-candidate-ledgerSkill
- exit-ticket-builderSkill
- extract-moduleSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Create a stable error interface that clients can depend on without parsing prose.
- Distinctive: line 13
Define one envelope: Use the repository's conventions where they exist.
- Distinctive: line 30
Model field errors structurally: Use stable field paths and codes.
- Distinctive: line 32
Implement centrally: Prefer typed domain errors plus one translation layer over hand-built responses in every handler.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Create a stable error interface that clients can depend on without parsing prose. Preserve compatibility where practical and make every change explicit.
Workflow
- Inventory current errors. Trace handlers, middleware, validators, domain errors, and exception fallbacks. Record status, body shape, machine code, message source, retry behavior, and whether sensitive detail can leak.
Define one envelope. Use the repository's conventions where they exist; otherwise design a minimal shape such as:
{ "error": { "code": "ORDER_ALREADY_PAID", "message": "This order has already been paid.", "request_id": "req_123", "fields": [{ "path": "email", "code": "INVALID_FORMAT" }], "retryable": false } }Omit optional fields when irrelevant. Keep machine codes stable, uppercase, and domain-specific.
- Map semantics deliberately. Assign statuses by protocol meaning: authentication, authorization, missing resource, conflict, validation, rate limit, upstream failure, and unexpected server error. Distinguish a safe retry from a permanent client error; add
Retry-Afteronly when the server can provide meaningful guidance. - Separate public and internal detail. Return safe messages. Log stack traces and internal context with the same request or correlation ID. Never expose SQL, filesystem paths, tokens, provider payloads, or raw exceptions.
- Model field errors structurally. Use stable field paths and codes. Do not concatenate multiple validation problems into one sentence clients must parse.
- Preserve compatibility. Build a before/after mapping. If existing clients depend on a legacy field, introduce the new envelope additively or version the breaking change; do not silently rename it.
- Implement centrally. Prefer typed domain errors plus one translation layer over hand-built responses in every handler. Update the OpenAPI schema and SDK types from the same contract.
- Add contract tests. Cover representative errors, the fallback 500 path, redaction, request IDs, field validation, and retry headers. Assert codes and structure rather than mutable message wording unless the message itself is contractual.
[!WARNING] Never let clients branch on
message. Prose changes for clarity and localization; machine codes are the compatibility surface.
Output
Return:
- the proposed error schema and code-naming rules
- a current-to-target mapping table for every discovered error path
- implementation edits to the central translator and typed errors
- updated API schema or documentation
- contract tests proving status, code, redaction, field details, retry semantics, and fallback behavior
- compatibility or rollout notes for existing clients
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

