How to Debug a Failing API Call with APXY

Every developer has been there: the request looks right in your code, but it fails at runtime. The error message is vague. The API docs do not help. You spend two hours guessing what is wrong.

APXY solves this by letting you see the exact request and response—headers, body, timing, status code—before and after your change. This tutorial walks you through the full debugging loop from install to confirmed fix.

What you will build

By the end of this tutorial you will have:

• Captured a failing HTTP request with APXY
• Identified the root cause from the raw request data
• Replayed the request after your fix to confirm the response changed

This is the same workflow used to debug everything from Stripe 422s to OpenAI rate limit errors.

Step 1: Install APXY

curl -fsSL https://apxy.dev/install.sh | bash

Then verify the install:

apxy --version

Step 2: Start the proxy

apxy start --port 8080

APXY starts a local HTTPS proxy and opens the Web UI at http://localhost:8081. You will see an empty traffic log—it fills in as requests flow through.

Step 3: Route your app through the proxy

Set the HTTPS_PROXY and HTTP_PROXY environment variables before running your app:

HTTPS_PROXY=http://localhost:8080 HTTP_PROXY=http://localhost:8080 node your-app.js

Or for curl:

curl -x http://localhost:8080 https://api.stripe.com/v1/payment_intents

Step 4: Reproduce the failure

Trigger the failing request as you normally would—run your app, click the button, call the API. The failing request appears in the APXY traffic log almost instantly.

Click on the request to open the detail view. You will see:

• Request: method, URL, headers, body
• Response: status code, headers, body
• Timing: total time, TTFB, SSL handshake

Look at the raw request first. Ask yourself: does the Content-Type header match what the API expects? Is the Authorization header present and correctly formatted? Is the request body valid JSON?

Step 5: Find the root cause

In this example, we are debugging a Stripe 422 Unprocessable Entity. The APXY request detail shows:

POST /v1/payment_intents
Authorization: Bearer sk_test_...
Content-Type: application/x-www-form-urlencoded

amount=4900&currency=usd

The response body from Stripe:

{
  "error": {
    "code": "parameter_missing",
    "message": "Missing required param: idempotency_key.",
    "type": "invalid_request_error"
  }
}

There it is. The Idempotency-Key header is missing. An AI-assisted code change removed it during a recent refactor.

Step 6: Apply your fix

Add the missing header back in your code:

const response = await fetch("https://api.stripe.com/v1/payment_intents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
    "Content-Type": "application/x-www-form-urlencoded",
    "Idempotency-Key": crypto.randomUUID(), // restored
  },
  body: new URLSearchParams({ amount: "4900", currency: "usd" }),
});

Step 7: Replay to confirm the fix

APXY has a Replay feature. Select the original failing request and click Replay. APXY re-sends the same request from the proxy. You will see a new entry in the traffic log.

Open the replayed request. The status code is now 200 OK and the response body contains the created payment intent.

You have evidence the fix worked—not just a feeling it should.

What to do next

Once you are comfortable with the basic debugging loop, explore these APXY features:

• Mock rules: Block or replace specific API calls so your frontend keeps moving even when the backend is down. See the mock templates for Stripe, GitHub, and OpenAI.
• Request diff: Compare two captured requests side by side to find subtle header or body differences.
• Export repro: Save the failing request as a cURL command and share it with a teammate or file it in a bug report.
• AI agent workflows: Point Claude Code or Cursor at your APXY traffic log and let the agent reason about the failure directly. See APXY with Cursor and APXY with Claude Code.

The pattern is always the same: capture, inspect, fix, replay. Once you have done it once you will not want to debug API calls without it.