Configuring Horizon
coollabsio/coolify
A skill your agent uses whenever the user mentions Horizon by name in a Laravel context.
API 에러 설계 패턴. An agent skill from revfactory/harness-100.
Install API Error Design
$ npx skills add revfactory/harness-100 --skill api-error-design -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install revfactory/harness-100 api-error-design --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/revfactory/harness-100.git skills-src && mkdir -p .claude/skills && cp -r skills-src/ko/18-api-designer/.claude/skills/api-error-design .claude/skills/api-error-design && rm -rf skills-srcUse ~/.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/
Install the "api-error-design" agent skill from https://github.com/revfactory/harness-100/tree/main/ko/18-api-designer/.claude/skills/api-error-design into .claude/skills/api-error-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "api-error-design", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/revfactory/harness-100/tree/main/ko/18-api-designer/.claude/skills/api-error-designType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add revfactory/harness-100 --skill api-error-design -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install revfactory/harness-100 api-error-design --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/revfactory/harness-100.git skills-src && mkdir -p .agents/skills && cp -r skills-src/ko/18-api-designer/.claude/skills/api-error-design .agents/skills/api-error-design && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "api-error-design" agent skill from https://github.com/revfactory/harness-100/tree/main/ko/18-api-designer/.claude/skills/api-error-design into .agents/skills/api-error-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "api-error-design", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add revfactory/harness-100 --skill api-error-design -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install revfactory/harness-100 api-error-design --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/revfactory/harness-100.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/ko/18-api-designer/.claude/skills/api-error-design .cursor/skills/api-error-design && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "api-error-design" agent skill from https://github.com/revfactory/harness-100/tree/main/ko/18-api-designer/.claude/skills/api-error-design into .cursor/skills/api-error-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "api-error-design", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/revfactory/harness-100.git --path ko/18-api-designer/.claude/skills/api-error-design--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add revfactory/harness-100 --skill api-error-design -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install revfactory/harness-100 api-error-design --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/revfactory/harness-100.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/ko/18-api-designer/.claude/skills/api-error-design .gemini/skills/api-error-design && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "api-error-design" agent skill from https://github.com/revfactory/harness-100/tree/main/ko/18-api-designer/.claude/skills/api-error-design into .gemini/skills/api-error-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "api-error-design", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install revfactory/harness-100 api-error-designInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add revfactory/harness-100 --skill api-error-design -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/revfactory/harness-100.git skills-src && mkdir -p .github/skills && cp -r skills-src/ko/18-api-designer/.claude/skills/api-error-design .github/skills/api-error-design && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "api-error-design" agent skill from https://github.com/revfactory/harness-100/tree/main/ko/18-api-designer/.claude/skills/api-error-design into .github/skills/api-error-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "api-error-design", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add revfactory/harness-100 --skill api-error-design -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install revfactory/harness-100 api-error-design --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/revfactory/harness-100.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/ko/18-api-designer/.claude/skills/api-error-design .opencode/skills/api-error-design && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "api-error-design" agent skill from https://github.com/revfactory/harness-100/tree/main/ko/18-api-designer/.claude/skills/api-error-design into .opencode/skills/api-error-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "api-error-design", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
api-error-design- GitHub stars
- 1.3k
- Token cost
- ~1.1k tokens
- SKILL.md length
- 426 words
- Files
- 1
- Skills in repo
- 464
- Repo updated
- First seen
- Licence
- Apache-2.0
At a glance
API 에러 설계 패턴. An agent skill from revfactory/harness-100.
- Works in 3 steps: 무엇이 잘못됐는가 — 문제 설명 → 왜 잘못됐는가 — 원인/제약 조건 → 어떻게 해결하는가 — 구체적 액션
- Backend & APIs work in your project
- SKILL.md covers 대상 에이전트, 에러 코드 체계 설계, 에러 응답 구조 표준 and 에러 메시지 작성 원칙, plus 2 more sections
- Needs AUTH_INVALID_CREDENTIALS
What it does
API Error Design is an agent skill from revfactory/harness-100. API 에러 설계 패턴. 에러 코드 체계, 에러 응답 구조, 클라이언트 친화적 에러 메시지, 에러 카탈로그 구축, retry/fallback 전략을 제공하는 doc-writer/mock-tester 확장 스킬. 'API 에러 설계', '에러 코드', '에러 응답', '에러 카탈로그', '에러 메시지', 'retry 전략' 등 API 에러 처리 체계 설계 시 사용한다. 단, 실제 에러 핸들링 코드 구현은 이 스킬의 범위가 아니다.
Its SKILL.md is about 1.1k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Backend & APIs. The licence is Apache-2.0.
When your agent uses it
- Backend & APIs work in your project
Example prompts
- “API 에러 설계”
- “retry 전략”
- “/api-error-design”
Workflow steps
3 steps, taken from the first numbered list in SKILL.md.
- 무엇이 잘못됐는가 — 문제 설명
- 왜 잘못됐는가 — 원인/제약 조건
- 어떻게 해결하는가 — 구체적 액션
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 loads about 1.1k tokens when it runs. Until then it costs about 65 tokens; SKILL.md has 426 words of instructions outside code blocks.
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). 426 words, ~1,129 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 에러 설계 패턴. 에러 코드 체계, 에러 응답 구조, 클라이언트 친화적 에러 메시지, 에러 카탈로그 구축, retry/fallback 전략을 제공하는 doc-writer/mock-tester 확장 스킬. 'API 에러 설계', '에러 코드', '에러 응답', '에러 카탈로그', '에러 메시지', 'retry 전략' 등 API 에러 처리 체계 설계 시 사용한다. 단, 실제 에러 핸들링 코드 구현은 이 스킬의 범위가 아니다.
API Error Design — API 에러 설계 패턴
doc-writer와 mock-tester 에이전트가 API 에러 문서화 및 테스트 설계 시 활용하는 에러 체계, 메시지 설계, 복구 전략 레퍼런스.
대상 에이전트
doc-writer— 에러 레퍼런스 문서 작성에 적용mock-tester— 에러 시나리오 테스트 설계에 적용
에러 코드 체계 설계
계층적 에러 코드 구조
{도메인}_{카테고리}_{상세}
예시:
AUTH_TOKEN_EXPIRED -- 인증 > 토큰 > 만료
ORDER_PAYMENT_DECLINED -- 주문 > 결제 > 거절
USER_VALIDATION_EMAIL -- 사용자 > 유효성 > 이메일도메인별 에러 코드 카탈로그
인증/인가 (AUTH)
| 코드 | HTTP | 메시지 | 클라이언트 액션 |
|---|---|---|---|
| AUTH_REQUIRED | 401 | 인증이 필요합니다 | 로그인 페이지로 이동 |
| AUTH_TOKEN_EXPIRED | 401 | 토큰이 만료되었습니다 | 토큰 갱신 시도 |
| AUTH_TOKEN_INVALID | 401 | 유효하지 않은 토큰입니다 | 재로그인 |
| AUTH_FORBIDDEN | 403 | 이 작업에 대한 권한이 없습니다 | 권한 요청 안내 |
| AUTH_ACCOUNT_LOCKED | 403 | 계정이 잠겼습니다. 15분 후 재시도하세요 | 대기 타이머 표시 |
| AUTH_INVALID_CREDENTIALS | 401 | 이메일 또는 비밀번호가 올바르지 않습니다 | 재입력 유도 |
유효성 검증 (VALIDATION)
| 코드 | HTTP | 메시지 | 필드별 상세 |
|---|---|---|---|
| VALIDATION_REQUIRED | 422 | 필수 필드가 누락되었습니다 | {field} 필드는 필수입니다 |
| VALIDATION_FORMAT | 422 | 형식이 올바르지 않습니다 | 유효한 {type}을 입력하세요 |
| VALIDATION_RANGE | 422 | 범위를 벗어났습니다 | {min}~{max} 사이 값을 입력하세요 |
| VALIDATION_UNIQUE | 409 | 이미 사용 중인 값입니다 | 이 {field}는 이미 등록되어 있습니다 |
| VALIDATION_LENGTH | 422 | 길이 제한을 초과했습니다 | {max}자 이내로 입력하세요 |
리소스 (RESOURCE)
| 코드 | HTTP | 메시지 |
|---|---|---|
| RESOURCE_NOT_FOUND | 404 | 요청한 리소스를 찾을 수 없습니다 |
| RESOURCE_ALREADY_EXISTS | 409 | 이미 존재하는 리소스입니다 |
| RESOURCE_DELETED | 410 | 삭제된 리소스입니다 |
| RESOURCE_LOCKED | 423 | 리소스가 잠겨 있습니다 |
Rate Limit
| 코드 | HTTP | 메시지 |
|---|---|---|
| RATE_LIMIT_EXCEEDED | 429 | 요청 한도를 초과했습니다. {retryAfter}초 후 재시도하세요 |
서버 (SERVER)
| 코드 | HTTP | 메시지 |
|---|---|---|
| SERVER_INTERNAL | 500 | 서버 오류가 발생했습니다. 잠시 후 재시도하세요 |
| SERVER_MAINTENANCE | 503 | 서비스 점검 중입니다 |
| SERVER_UPSTREAM | 502 | 외부 서비스 연결에 실패했습니다 |
에러 응답 구조 표준
기본 구조
{
"error": {
"code": "AUTH_TOKEN_EXPIRED",
"message": "토큰이 만료되었습니다",
"detail": "access token의 유효기간이 지났습니다. refresh token으로 갱신하세요.",
"timestamp": "2025-03-15T09:30:00Z",
"requestId": "req_abc123def456",
"path": "/api/v1/users/me"
}
}유효성 검증 에러 (필드별)
{
"error": {
"code": "VALIDATION_ERROR",
"message": "입력값이 올바르지 않습니다",
"errors": [
{
"field": "email",
"code": "VALIDATION_FORMAT",
"message": "유효한 이메일 주소를 입력하세요",
"value": "invalid-email"
},
{
"field": "password",
"code": "VALIDATION_LENGTH",
"message": "비밀번호는 8자 이상이어야 합니다",
"constraint": { "min": 8 }
}
]
}
}에러 메시지 작성 원칙
좋은 에러 메시지의 3요소
- 무엇이 잘못됐는가 — 문제 설명
- 왜 잘못됐는가 — 원인/제약 조건
- 어떻게 해결하는가 — 구체적 액션
Show full SKILL.md (172 more words)Show less
Do / Don't
| Don't | Do |
|---|---|
| "Error occurred" | "주문 생성에 실패했습니다" |
| "Invalid input" | "가격은 0보다 큰 숫자여야 합니다" |
| "Server error: NullPointerException at..." | "서버 오류가 발생했습니다. 잠시 후 재시도하세요" |
| "Access denied" | "이 주문을 수정할 권한이 없습니다. 관리자에게 문의하세요" |
| "Duplicate key constraint violation" | "이 이메일은 이미 등록되어 있습니다" |
다국어 에러 메시지 구조
{
"error": {
"code": "VALIDATION_REQUIRED",
"message": "필수 필드가 누락되었습니다",
"messageKey": "error.validation.required",
"params": { "field": "email" }
}
}Retry/Fallback 전략
Retry 가능 여부 판단
| HTTP 상태 | Retry 가능? | 전략 |
|---|---|---|
| 408 | O | 즉시 재시도 |
| 429 | O | Retry-After 헤더 대기 후 |
| 500 | O (조건부) | 지수 백오프 |
| 502, 503, 504 | O | 지수 백오프 |
| 400, 401, 403, 404 | X | 클라이언트 수정 필요 |
| 409, 422 | X | 입력값 수정 필요 |
지수 백오프 (Exponential Backoff)
대기시간 = min(baseDelay * 2^attempt + jitter, maxDelay)
예시: baseDelay=1초, maxDelay=30초
시도 1: 1초 + 랜덤(0~500ms)
시도 2: 2초 + 랜덤(0~500ms)
시도 3: 4초 + 랜덤(0~500ms)
시도 4: 8초 + 랜덤(0~500ms)
최대 3~5회 시도에러 테스트 시나리오 매트릭스
| 카테고리 | 테스트 케이스 | 기대 코드 |
|---|---|---|
| 인증 없음 | Authorization 헤더 없이 요청 | 401 |
| 만료 토큰 | 만료된 JWT로 요청 | 401 |
| 권한 없음 | 다른 사용자 리소스 접근 | 403 |
| 존재하지 않는 ID | 랜덤 UUID로 조회 | 404 |
| 필수 필드 누락 | body에서 필수 필드 제거 | 422 |
| 잘못된 형식 | 이메일 필드에 "abc" | 422 |
| 중복 생성 | 같은 데이터로 POST 2회 | 409 |
| 대량 요청 | Rate Limit 초과 | 429 |
| 잘못된 JSON | {invalid json 전송 | 400 |
| 빈 바디 | Content-Length: 0 | 400 |
© 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 ko/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 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.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| API Error Design this skillrevfactory/harness-100 | 1.3k | — | ~1.1k | Automated safety check: Pass | Apache-2.0 | |
| Configuring Horizoncoollabsio/coolify | 63k | 4 repos | ~898 | Automated safety check: Pass | MIT | |
| Nestjs Best Practicesrolling-scopes/rsschool-app | 10k | 6 repos | ~1.2k | Automated safety check: Pass | MIT | |
| Sub2API AdminWei-Shaw/sub2api | 43k | 1 repos | ~717 | Automated safety check: Pass | LGPL-3.0 | |
| Firecrawl Build Onboardingfirecrawl/firecrawl | 189k | 1 repos | ~1.4k | Automated safety check: Notes | ISC | |
| Obsidian BasesAtmosphere/atmosphere | 3.8k | 22 repos | ~3.2k | Automated safety check: Pass | Apache-2.0 |
Similar skills
Nestjs Best Practices
rolling-scopes/rsschool-app
NestJS best practices and architecture patterns for building production-ready applications.
Sub2API Admin
Wei-Shaw/sub2api
Manages a Sub2API deployment from the command line: accounts, redeem and invitation codes, groups, proxies, imports, exports and raw admin API calls.
Firecrawl Build Onboarding
firecrawl/firecrawl
Gets Firecrawl working in a project: signs you in through the browser, saves FIRECRAWL_API_KEY to .env and picks the first SDK or REST path.
Obsidian Bases
Atmosphere/atmosphere
Create and edit Obsidian Bases (.base files) with views, filters, formulas, and summaries.
Fortify Development
coollabsio/coolify
ACTIVATE when the user works on authentication in Laravel. An agent skill from coollabsio/coolify.
More from revfactory/harness-100
All 464 skills in this repoAnti Bot Analyzer
revfactory/harness-100
A skill for analyzing website anti-bot defense mechanisms and developing legitimate evasion strategies.
API Error Design Patterns
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.
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.
Arg Parser Generator
revfactory/harness-100
Methodology for systematically designing and generating CLI tool argument parser structures.
Audience Segmentation
revfactory/harness-100
Audience segmentation skill used by the analyst and curator agents.
Audio Storytelling
revfactory/harness-100
Audio storytelling skill used by the podcast scriptwriter and show note editor.
Related
Categories
Questions about API Error Design
What does API Error Design do?
API 에러 설계 패턴. An agent skill from revfactory/harness-100. API Error Design is an agent skill from revfactory/harness-100. API 에러 설계 패턴.
When should I use API Error Design?
API Error Design fits situations like: backend & APIs work in your project.
How do I install API Error Design in Claude Code?
Run `npx skills add revfactory/harness-100 --skill api-error-design -a claude-code`. Or copy the skill folder (ko/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 in Codex?
Run `npx skills add revfactory/harness-100 --skill api-error-design -a codex`. Or copy the skill folder (ko/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 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 need to run?
Going by SKILL.md and its folder, API Error Design needs credentials named AUTH_INVALID_CREDENTIALS.
Does API Error Design 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 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 use?
API Error Design 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 use?
About 1.1k tokens (SKILL.md is roughly 4.5k 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?
Skills that share tags, products or a category with API Error Design: Configuring Horizon (coollabsio/coolify, 63k stars), Nestjs Best Practices (rolling-scopes/rsschool-app, 10k stars), Sub2API Admin (Wei-Shaw/sub2api, 43k stars) and Firecrawl Build Onboarding (firecrawl/firecrawl, 189k 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?
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.