New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

API Error Design Patterns

by revfactory in revfactory/harness-100

Reference for designing how an API reports failures: structured error codes, response shapes, client-friendly messages, an error catalog and retry or fallback advice.

Apache-2.0Auto-check passedBackend & APIs

Install API Error Design Patterns

skills CLI
$ npx skills add revfactory/harness-100 --skill api-error-design -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install revfactory/harness-100 api-error-design --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/revfactory/harness-100.git skills-src && mkdir -p .claude/skills && cp -r skills-src/en/18-api-designer/.claude/skills/api-error-design .claude/skills/api-error-design && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
api-error-design
GitHub stars
1.3k
Token cost
~1.6k tokens
SKILL.md length
492 words
Files
1
Skills in repo
464
Repo updated
First seen
Licence
Apache-2.0

At a glance

Reference for designing how an API reports failures: structured error codes, response shapes, client-friendly messages, an error catalog and retry or fallback advice.

  • Works in 3 steps: What went wrong — Describe the problem → Why it went wrong — Explain the cause or… → How to fix it — Provide a specific action
  • Designing an error code scheme for a new REST API
  • SKILL.md covers Target Agents, Error Code System Design, Error Response Structure… and Error Message Writing Principles, plus 2 more sections
  • Needs AUTH_INVALID_CREDENTIALS

What it does

This is a reference that the doc-writer and mock-tester agents of its harness consult when they document or test how an API fails. It proposes a hierarchical error code format built from a domain, a category and a detail, then supplies a catalog grouped by domain: authentication and authorization, validation, resource, rate limit and server errors.

Each catalog row pairs a code with an HTTP status and a client-facing message, and where it helps adds a suggested client action or field-level hint. Examples include sending an expired token to a refresh attempt, returning 422 for a missing field, or answering 429 with a retry-after wait. The skill covers design and documentation only; writing the actual error handling code is outside its scope.

When your agent uses it

  • Designing an error code scheme for a new REST API
  • Writing an error reference page for the people who consume an API
  • Planning error scenario tests that cover auth, validation and rate limit cases
  • Drafting client-friendly error messages and retry guidance

Example prompts

  • “Design an error code catalog for our orders API, grouped by domain.”
  • “Write user-facing messages for the validation errors that the signup endpoint returns.”
  • “What retry and fallback behavior should clients have for 503 and 429 responses?”

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. What went wrong — Describe the problem
  2. Why it went wrong — Explain the cause or constraint
  3. How to fix it — Provide a specific action

What it can do on your machine

Read from SKILL.md and the folder at commit 8e8d35c. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are json).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • AUTH_INVALID_CREDENTIALS

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

API Error Design Patterns loads about 1.6k tokens when it runs. Until then it costs about 124 tokens; SKILL.md has 492 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~124
When it runs · the whole SKILL.md, loaded when a task matches
~1.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from revfactory/harness-100 at commit 8e8d35c, republished under its Apache-2.0 licence (© revfactory). 492 words, ~1,571 tokens.

Download SKILL.mdSave it as .claude/skills/api-error-design/SKILL.md (or your agent's skills folder).
name
api-error-design
description
API error design patterns. An extension skill for doc-writer/mock-tester that provides error code systems, error response structures, client-friendly error messages, error catalog construction, and retry/fallback strategies. Use when designing API error handling systems involving 'API error design', 'error codes', 'error responses', 'error catalogs', 'error messages', 'retry strategies', etc. Note: actual error handling code implementation is outside the scope of this skill.

API Error Design — API Error Design Patterns

A reference for error systems, message design, and recovery strategies used by the doc-writer and mock-tester agents when designing API error documentation and tests.

Target Agents

  • doc-writer — Applied when writing error reference documentation
  • mock-tester — Applied when designing error scenario tests

Error Code System Design

Hierarchical Error Code Structure
{DOMAIN}_{CATEGORY}_{DETAIL}

Examples:
AUTH_TOKEN_EXPIRED        -- Authentication > Token > Expired
ORDER_PAYMENT_DECLINED    -- Order > Payment > Declined
USER_VALIDATION_EMAIL     -- User > Validation > Email
Error Code Catalog by Domain
Authentication/Authorization (AUTH)
CodeHTTPMessageClient Action
AUTH_REQUIRED401Authentication is requiredRedirect to login page
AUTH_TOKEN_EXPIRED401Token has expiredAttempt token refresh
AUTH_TOKEN_INVALID401Invalid tokenRe-authenticate
AUTH_FORBIDDEN403You do not have permission for this actionGuide user to request permissions
AUTH_ACCOUNT_LOCKED403Account is locked. Please retry after 15 minutesDisplay wait timer
AUTH_INVALID_CREDENTIALS401Invalid email or passwordPrompt re-entry
Validation (VALIDATION)
CodeHTTPMessageField-Level Detail
VALIDATION_REQUIRED422Required field is missingThe {field} field is required
VALIDATION_FORMAT422Invalid formatPlease enter a valid {type}
VALIDATION_RANGE422Value is out of rangePlease enter a value between {min} and {max}
VALIDATION_UNIQUE409Value is already in useThis {field} is already registered
VALIDATION_LENGTH422Length limit exceededPlease enter no more than {max} characters
Resource (RESOURCE)
CodeHTTPMessage
RESOURCE_NOT_FOUND404The requested resource was not found
RESOURCE_ALREADY_EXISTS409Resource already exists
RESOURCE_DELETED410Resource has been deleted
RESOURCE_LOCKED423Resource is locked
Rate Limit
CodeHTTPMessage
RATE_LIMIT_EXCEEDED429Request limit exceeded. Please retry after {retryAfter} seconds
Server (SERVER)
CodeHTTPMessage
SERVER_INTERNAL500A server error occurred. Please retry shortly
SERVER_MAINTENANCE503Service is under maintenance
SERVER_UPSTREAM502Failed to connect to an external service

Error Response Structure Standard

Basic Structure
json
{
  "error": {
    "code": "AUTH_TOKEN_EXPIRED",
    "message": "Token has expired",
    "detail": "The access token has expired. Please refresh using your refresh token.",
    "timestamp": "2025-03-15T09:30:00Z",
    "requestId": "req_abc123def456",
    "path": "/api/v1/users/me"
  }
}
Validation Error (Per-Field)
json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input values are invalid",
    "errors": [
      {
        "field": "email",
        "code": "VALIDATION_FORMAT",
        "message": "Please enter a valid email address",
        "value": "invalid-email"
      },
      {
        "field": "password",
        "code": "VALIDATION_LENGTH",
        "message": "Password must be at least 8 characters",
        "constraint": { "min": 8 }
      }
    ]
  }
}

Error Message Writing Principles

Three Elements of a Good Error Message
  1. What went wrong — Describe the problem
  2. Why it went wrong — Explain the cause or constraint
  3. How to fix it — Provide a specific action
Show full SKILL.md (182 more words)Show less
Do / Don't
Don'tDo
"Error occurred""Failed to create the order"
"Invalid input""Price must be a number greater than 0"
"Server error: NullPointerException at...""A server error occurred. Please retry shortly"
"Access denied""You do not have permission to modify this order. Please contact an administrator"
"Duplicate key constraint violation""This email is already registered"
Multilingual Error Message Structure
json
{
  "error": {
    "code": "VALIDATION_REQUIRED",
    "message": "Required field is missing",
    "messageKey": "error.validation.required",
    "params": { "field": "email" }
  }
}

Retry/Fallback Strategy

Retry Eligibility
HTTP StatusRetryable?Strategy
408YesRetry immediately
429YesWait per Retry-After header
500Yes (conditional)Exponential backoff
502, 503, 504YesExponential backoff
400, 401, 403, 404NoClient-side fix required
409, 422NoInput correction required
Exponential Backoff
wait_time = min(baseDelay * 2^attempt + jitter, maxDelay)

Example: baseDelay=1s, maxDelay=30s
Attempt 1: 1s + random(0~500ms)
Attempt 2: 2s + random(0~500ms)
Attempt 3: 4s + random(0~500ms)
Attempt 4: 8s + random(0~500ms)
Maximum 3-5 attempts

Error Test Scenario Matrix

CategoryTest CaseExpected Code
No authenticationRequest without Authorization header401
Expired tokenRequest with expired JWT401
No permissionAccess another user's resource403
Non-existent IDQuery with random UUID404
Missing required fieldRemove required field from body422
Invalid format"abc" in email field422
Duplicate creationPOST same data twice409
Bulk requestsExceed Rate Limit429
Malformed JSONSend {invalid json400
Empty bodyContent-Length: 0400

© revfactory, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in en/18-api-designer/.claude/skills/api-error-design of revfactory/harness-100.

Open the folder on GitHubat commit 8e8d35c

Compare with similar skills

API Error Design Patterns next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

API Error Design Patterns compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
API Error Design Patterns this skillrevfactory/harness-1001.3k—~1.6kAutomated safety check: PassApache-2.0
OpenAPI Spec Generationwshobson/agents40k9 repos~511Automated safety check: PassMIT
Docs Interfacesjh941213/my-cc-harness126—~863Automated safety check: NotesNone
Error Handlingericrisco/rsc-harness156—~3.2kAutomated safety check: PassMIT
API DesignerJeffallan/claude-skills12k2 repos~2kAutomated safety check: PassMIT
API Route Patternsbybren-llc/safe-agentic-workflow421—~1.6kAutomated safety check: PassMIT

Similar skills

  • OpenAPI Spec Generation

    wshobson/agents

    Create, validate and maintain OpenAPI 3.1 specs for REST APIs, whether designed first or generated from existing code, and use them for docs and client SDKs.

    40k GitHub starsUsed in 9 repos~511 tokens
    Backend & APIsAuto-check passed

  • Docs Interfaces

    jh941213/my-cc-harness

    Generate interface/API docs — OpenAPI 3.1/AsyncAPI 3.0 specs, API topology diagrams, interface flow (sequence) diagrams, API changelog.

    126 GitHub stars~863 tokensUpdated 2 mo ago
    Backend & APIsAuto-check: notes

  • Error Handling

    ericrisco/rsc-harness

    A skill your agent uses when designing the reaction to a class of failures — typed error taxonomies, retry/backoff/timeout policy, circuit breakers, React/Next error boundaries, and the user-message…

    156 GitHub stars~3.2k tokensUpdated today
    Backend & APIsAuto-check passed

  • API Designer

    Jeffallan/claude-skills

    Designs REST and GraphQL APIs from resource modeling to an OpenAPI 3.1 contract, with versioning, pagination and RFC 7807 error handling.

    12k GitHub starsUsed in 2 repos~2k tokens
    Backend & APIsAuto-check passed

  • API Route Patterns

    bybren-llc/safe-agentic-workflow

    API route implementation patterns with RLS, validation, and error handling. Use when creating API routes, implementing CRUD endpoints, adding server-side…

    421 GitHub stars~1.6k tokensUpdated 2 mo ago
    Backend & APIsAuto-check passed

  • Rust Skills

    JMBeresford/retrom

    Comprehensive Rust coding guidelines with 265 rules across 26 categories.

    2.1k GitHub starsUsed in 1 repo~9.5k tokens
    DevelopmentAuto-check passed

More from revfactory/harness-100

All 464 skills in this repo

  • Anti Bot Analyzer

    revfactory/harness-100

    A skill for analyzing website anti-bot defense mechanisms and developing legitimate evasion strategies.

    1.3k GitHub stars~1.1k tokensUpdated 6 mo ago
    Auto-check passed

  • API Security Checklist

    revfactory/harness-100

    Walks a backend-dev agent through OWASP API Top 10 checks, authentication and authorization patterns, and defense code during API design.

    1.3k GitHub stars~1.7k tokensUpdated 6 mo ago
    Auto-check passed

  • Arg Parser Generator

    revfactory/harness-100

    Methodology for systematically designing and generating CLI tool argument parser structures.

    1.3k GitHub stars~1.2k tokensUpdated 6 mo ago
    Auto-check passed

  • Audience Segmentation

    revfactory/harness-100

    Audience segmentation skill used by the analyst and curator agents.

    1.3k GitHub stars~1.3k tokensUpdated 6 mo ago
    Auto-check passed

  • Audio Storytelling

    revfactory/harness-100

    Audio storytelling skill used by the podcast scriptwriter and show note editor.

    1.3k GitHub stars~1.6k tokensUpdated 6 mo ago
    Auto-check passed

  • Audit Checklist Engine

    revfactory/harness-100

    A systematic checklist generation engine for compliance audits.

    1.3k GitHub stars~1.3k tokensUpdated 6 mo ago
    Auto-check passed

Categories

Questions about API Error Design Patterns

What does API Error Design Patterns do?

Reference for designing how an API reports failures: structured error codes, response shapes, client-friendly messages, an error catalog and retry or fallback advice. This is a reference that the doc-writer and mock-tester agents of its harness consult when they document or test how an API fails. It proposes a hierarchical error code format built from a domain, a category and a detail, then supplies a catalog grouped by domain: authentication and authorization, validation, resource, rate limit and server errors.

When should I use API Error Design Patterns?

API Error Design Patterns fits situations like: designing an error code scheme for a new REST API; writing an error reference page for the people who consume an API; planning error scenario tests that cover auth, validation and rate limit cases; drafting client-friendly error messages and retry guidance.

How do I install API Error Design Patterns in Claude Code?

Run `npx skills add revfactory/harness-100 --skill api-error-design -a claude-code`. Or copy the skill folder (en/18-api-designer/.claude/skills/api-error-design in revfactory/harness-100) into .claude/skills/api-error-design in your project. Claude Code loads it when a task matches its description.

How do I install API Error Design Patterns in Codex?

Run `npx skills add revfactory/harness-100 --skill api-error-design -a codex`. Or copy the skill folder (en/18-api-designer/.claude/skills/api-error-design in revfactory/harness-100) into .agents/skills/api-error-design in your project. Codex loads it when a task matches its description.

Can I use API Error Design Patterns in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add revfactory/harness-100 --skill api-error-design -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/api-error-design, .gemini/skills/api-error-design, .github/skills/api-error-design and .opencode/skills/api-error-design in your project.

What does API Error Design Patterns need to run?

Going by SKILL.md and its folder, API Error Design Patterns needs credentials named AUTH_INVALID_CREDENTIALS.

Does API Error Design Patterns access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is API Error Design Patterns safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does API Error Design Patterns use?

API Error Design Patterns is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does API Error Design Patterns use?

About 1.6k tokens (SKILL.md is roughly 6.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to API Error Design Patterns?

Skills that share tags, products or a category with API Error Design Patterns: OpenAPI Spec Generation (wshobson/agents, 40k stars), Docs Interfaces (jh941213/my-cc-harness, 126 stars), Error Handling (ericrisco/rsc-harness, 156 stars) and API Designer (Jeffallan/claude-skills, 12k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains API Error Design Patterns?

revfactory (a GitHub user) maintains it in revfactory/harness-100, which has 1,290 GitHub stars. The repository holds 464 skills in this directory. The repository was last updated on March 22, 2026.

Source: revfactory/harness-100 on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.