Agent Skills › ownpilot/OwnPilot › api-debugging

api-debugging

GitHub

提供系统化的 REST API 调试方法，涵盖 HTTP 错误、认证问题及网络故障排查。通过复现请求、隔离问题、检查状态码并应用修复方案，帮助用户解决 API 调用中的各类异常。

packages/gateway/data/example-skills/api-debugging/SKILL.md ownpilot/OwnPilot

触发场景

用户遇到 API 错误或状态码问题需要排查 HTTP 请求故障或超时问题

安装

npx skills add ownpilot/OwnPilot --skill api-debugging -g -y

更多选项

非标准路径

npx skills add https://github.com/ownpilot/OwnPilot/tree/main/packages/gateway/data/example-skills/api-debugging -g -y

不安装直接使用

npx skills use ownpilot/OwnPilot@api-debugging

指定 Agent (Claude Code)

npx skills add ownpilot/OwnPilot --skill api-debugging -a claude-code -g -y

安装 repo 全部 skill

npx skills add ownpilot/OwnPilot --all -g -y

预览 repo 内 skill

npx skills add ownpilot/OwnPilot --list

SKILL.md

Frontmatter

{
    "name": "api-debugging",
    "license": "MIT",
    "metadata": {
        "author": "ownpilot",
        "version": "1.0.0"
    },
    "description": "Systematic approach to debugging REST APIs, HTTP errors, authentication issues, and network problems. Use when the user has API errors, status code issues, timeout problems, or needs help troubleshooting HTTP requests.",
    "allowed-tools": "Bash(curl:*) Bash(wget:*)",
    "compatibility": "Works best with code execution enabled for running curl\/fetch commands"
}

API Debugging

You are an expert API debugger. Follow this systematic process when helping troubleshoot API issues.

Debugging Workflow

Reproduce — Get the exact request that fails (URL, method, headers, body)
Isolate — Is it the request, the server, auth, or network?
Check basics — Status code, response body, headers
Fix — Apply the solution
Verify — Confirm the fix works

HTTP Status Code Guide

Client Errors (4xx)

Code	Meaning	Common Cause	Fix
400	Bad Request	Malformed JSON, missing field	Check request body schema
401	Unauthorized	Missing/expired token	Refresh auth token
403	Forbidden	Insufficient permissions	Check API key scopes
404	Not Found	Wrong URL or deleted resource	Verify endpoint path
405	Method Not Allowed	GET instead of POST	Check HTTP method
409	Conflict	Duplicate resource	Check unique constraints
422	Unprocessable	Validation failed	Check field types/values
429	Too Many Requests	Rate limited	Add retry with backoff

Server Errors (5xx)

Code	Meaning	Action
500	Internal Server Error	Check server logs, report bug
502	Bad Gateway	Upstream service down, retry
503	Service Unavailable	Service overloaded, wait and retry
504	Gateway Timeout	Increase timeout, check slow queries

Authentication Checklist

When auth fails (401/403):

Is the token/key present in the request?
Is it in the right header? (Authorization: Bearer <token> vs X-API-Key: <key>)
Has the token expired? (Decode JWT at jwt.io to check exp)
Are the scopes/permissions sufficient?
Is there an IP allowlist blocking the request?
Is the API key for the correct environment (prod vs staging)?

Common Patterns

Retry with exponential backoff

Wait: 1s → 2s → 4s → 8s (max 3-4 retries)
Only retry on: 429, 500, 502, 503, 504
Never retry on: 400, 401, 403, 404

Debug steps for timeout issues

Is the endpoint correct? (Try a simple GET first)
Is the payload too large?
Is the server under load? (Check response time headers)
Is there a proxy/firewall in the way?
Try with a longer timeout to confirm it's not just slow

CORS issues (browser only)

Error: "No Access-Control-Allow-Origin header"
Fix: Server must add Access-Control-Allow-Origin header
Workaround: Use server-side proxy, not browser fetch

Request Debugging Template

When analyzing a failed request, gather:

Endpoint:  [METHOD] [URL]
Headers:   [Key headers, especially Auth]
Body:      [Request payload]
Status:    [Response status code]
Response:  [Error message or body]
Timing:    [How long did it take?]
Context:   [When did it start failing? What changed?]