Skip to content This library is free, offered as dana. If it helps your work, donate here →
penguin tree ai
← back to libraryDonate here

This is one of 3,622 free prompts in the penguin tree ai library. Sign up once and the whole library opens, with new prompts by email.

open the library →

API debugging checklist

Generates a systematic API debugging checklist for a specific failing REST or SOAP integration, walking through authentication, endpoint construction, request payload, headers, rate limiting, and response code…

download .md

Purpose

Turn a vague "the API isn't working" report into a systematic, ordered debugging checklist tailored to the specific failing call — isolating whether the problem lives in auth, the endpoint, the payload, headers, rate limits, or the server response, and delivering ranked likely causes plus Postman-ready reproduction steps.

When to Use

Invoke this skill when the user asks to:

  • Debug a REST or SOAP API call that's failing or returning errors
  • Troubleshoot a 401, 403, 404, 429, 500, or other unexpected HTTP status code
  • Diagnose why an integration stopped working or never worked
  • Investigate malformed or rejected request payloads
  • Figure out why an API call works in one environment but not another
  • Reproduce a customer-reported API failure step by step

Inputs Required

Before starting, collect:

  • API type: REST or SOAP (and the provider/service if known)
  • Failing request: The endpoint URL, HTTP method, and — if available — the request body/envelope
  • Error symptom: The exact status code, error message, or observed behavior
  • Auth method: API key / Bearer token / OAuth 2.0 / Basic Auth / WS-Security / mTLS
  • Environment: Production / staging / sandbox, and whether it works elsewhere
  • Headers sent: Content-Type, Accept, custom headers (if known)
  • Recent changes: Any deploys, credential rotations, or config changes near when it broke

If the request body or headers aren't available, generate the checklist against the most common defaults for the stated API type and flag the assumption.

Instructions

Build the checklist by walking the request lifecycle in order. Each layer must be cleared before moving to the next — most failures are caught in the first three layers. For each check, state what to verify, how to verify it (Postman step or header/value to inspect), and what the failure looks like.

Step 1: Authentication & Authorization

The most common source of API failures. Diagnose by symptom:

  • 401 Unauthorized: Credential missing, malformed, or expired. Verify the auth header is present and correctly formatted (Authorization: Bearer <token> — check for missing "Bearer " prefix, trailing whitespace, or wrong casing). For OAuth 2.0, confirm the token hasn't expired and the correct grant type was used.
  • 403 Forbidden: Authenticated but not permitted. Verify the token/key has the required scopes or permissions for this endpoint, and that the account/tenant matches the resource.
  • SOAP WS-Security: Confirm the <wsse:Security> header is present, the timestamp is within the allowed skew, and the digest/signature matches.
  • mTLS: Confirm the client certificate is presented and not expired.
  • Postman step: Set auth in the Authorization tab (not manually in Headers to avoid double-encoding), then inspect the raw generated header via the Code snippet view.

Step 2: Endpoint & URL Construction

  • Verify the base URL matches the environment (sandbox vs. production hosts are frequently swapped).
  • Confirm the HTTP method matches what the endpoint expects (POST vs. PUT vs. PATCH).
  • Check the path — trailing slashes, API version segment (/v1/ vs /v2/), and correct resource identifiers.
  • Inspect query parameters for encoding issues (spaces, special characters, unencoded &).
  • 404 Not Found: Wrong path, wrong version, or resource ID doesn't exist. 405 Method Not Allowed: Correct path, wrong verb.
  • SOAP: Confirm the request is POSTed to the correct service endpoint and the SOAPAction header matches the operation.

Step 3: Request Payload & Body

  • REST: Validate the JSON is well-formed (no trailing commas, unescaped quotes, or wrong data types). Confirm required fields are present and field names match the schema exactly (case-sensitive).
  • SOAP: Validate the XML against the WSDL — namespaces, element order, and required elements must match. A single wrong namespace prefix causes rejection.
  • 400 Bad Request / 422 Unprocessable Entity: Read the response body — most APIs name the offending field. Map the error to the specific field or validation rule.
  • Check for size limits on the payload.
  • Postman step: Use the Body tab set to raw + JSON/XML; validate JSON with Postman's built-in linter before sending.

Step 4: Headers & Content Negotiation

  • Content-Type: Must match the actual body format (application/json, application/xml, text/xml for SOAP). A JSON body with the wrong Content-Type is silently rejected or mis-parsed.
  • Accept: Confirm the client accepts the format the server returns.
  • 415 Unsupported Media Type: Content-Type mismatch — the most common cause.
  • Check for required custom headers (idempotency keys, API version headers, request IDs, correlation IDs).

Step 5: Rate Limits & Throttling

  • 429 Too Many Requests: Inspect Retry-After, X-RateLimit-Remaining, and X-RateLimit-Reset headers to confirm the limit and reset window.
  • Determine whether the limit is per-key, per-IP, per-account, or per-endpoint.
  • Recommend exponential backoff with jitter for retry logic, and confirm the client isn't retrying aggressively into the limit.
  • Rule out that a burst from other integrations sharing the same credential is consuming the quota.

Step 6: Response Code & Server-Side Interpretation

  • 5xx errors (500/502/503/504): Generally server-side. Confirm reproducibility — a one-off 503 may be transient. Capture the response body and any correlation/request ID to hand to the provider's support.
  • Timeouts (504 / connection reset): Check whether the request is long-running and needs an async pattern or increased client timeout.
  • Distinguish provider outages (check the provider's status page) from request-specific failures.

Step 7: Ranked Likely Root Causes

Based on the stated symptom, produce a ranked list of the 3–5 most probable causes — most likely first — each with the single fastest check to confirm or eliminate it.

Step 8: Postman Reproduction Steps

Provide a copy-followable sequence to reproduce the exact failing call in Postman: method, URL, auth setup, headers, body, and what a successful vs. failing response looks like.

Output Format

  • Structure: Sequential checklist organized by the 6 debugging layers, followed by ranked root causes and Postman reproduction steps
  • Length: 700–1,000 words
  • Format: Checkboxes (- [ ]) for each verifiable check within layers; ranked causes as a numbered list; Postman steps as an ordered walkthrough
  • Sections: Auth & Authz → Endpoint & URL → Payload & Body → Headers → Rate Limits → Response Code → Ranked Root Causes → Postman Reproduction
  • Tone: Support/integration engineer — precise, symptom-driven, no filler; every check is actionable

Quality Checklist

Before delivering output, verify:

  • [ ] The checklist is tailored to the stated API type (REST vs. SOAP checks differ — don't emit both if only one applies)
  • [ ] Every layer maps at least one specific status code or symptom to a concrete check
  • [ ] Ranked root causes are ordered by likelihood for the stated symptom — not generic
  • [ ] Each root cause includes the single fastest check to confirm or eliminate it
  • [ ] Postman reproduction steps include auth setup, headers, and body — not just the URL
  • [ ] Checks reference actual header names and values (e.g., Retry-After, Authorization: Bearer) rather than vague instructions

Notes

  • Roughly 70% of API failures are caught in the first three layers (auth, endpoint, payload) — always clear those before investigating rate limits or server errors.
  • The single fastest diagnostic is often reading the response body: most well-designed APIs name the exact failing field or scope. Don't guess before reading it.
  • "Works in Postman but not in code" almost always means a header, encoding, or auth difference — compare Postman's generated code snippet against the actual client request.
  • For intermittent failures, capture the correlation/request ID before escalating to the provider — it's the first thing their support will ask for.

How to use this skill

This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.

Installing in Claude Code:

  • ~/.claude/skills/<folder-name>/SKILL.md — auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)
  • <your-project>/.claude/skills/<folder-name>/SKILL.md — auto-loads only when working in that project (recommended for project-specific skills)

Restart Claude Code or open a new session to register.

Using in Claude.ai, ChatGPT, Gemini, or other AI tools:

  1. Drag this file into a new chat, or copy and paste its contents
  2. Send your task or request as your next message — the AI will apply the skill where it fits

For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills