How to Monitor the Stripe API Health and Catch Payment Outages Before Your Customers Do

When Stripe goes down, your revenue goes with it. It does not matter how fast your servers are, how polished your checkout flow looks, or how many abandoned-cart emails you have queued up. If the payment processor cannot accept charges, your business is frozen. And the scary part is that Stripe outages are rarely the clean, total blackouts the news reports on. Partial degradation is far more common. The API responds slowly, certain endpoints fail while others work, webhook deliveries stop arriving, or a single region silently misses payments for 20 minutes while the dashboard shows all green.

If you are waiting for status.stripe.com to tell you something is wrong, you are already behind. Public status pages are updated by humans, after an incident has been confirmed internally, and that process typically lags real customer impact by 15 to 30 minutes. Stripe also exposes a machine-readable summary at https://status.stripe.com/api/v2/summary.json, but that endpoint reflects exactly the same manual update lag as the HTML status page. Polling it is not a substitute for a real API probe. By the time the yellow banner appears, a measurable chunk of your customers have already failed to check out, cursed at their screens, and left. In this tutorial you will set up a free Stripe API health monitor that catches outages in about 5 minutes instead of 30, and validates the actual JSON body Stripe returns rather than trusting a hollow 200 OK.

Why Stripe's Status Page Is Not a Monitoring Tool

Stripe's status page is a helpful communication channel. It is not a monitoring system, and it was never meant to be one. Treating it as your first line of defense creates four specific blind spots that hit payment infrastructure harder than almost any other kind of dependency.

• Manual update lag. Stripe's status is updated by humans after an internal incident review. The gap between customers failing to check out and the status page turning yellow is commonly 15 minutes and can stretch past 30. By the time the banner appears, you are doing damage control, not detection.
• Partial outages never hit the threshold. If only the PaymentIntents endpoint is slow but Customers and Balance are fine, Stripe's incident classification may not mark it a public incident. Your checkout flow is still broken, but status.stripe.com will show all green.
• Your integration can fail in unique ways. A bug that only affects a specific Stripe Connect feature, a particular API version pinned to your account, or a regional edge node will never show up on a global status page even when it shows up in your revenue numbers.
• Account-level issues are fully invisible. Rotated API keys, expired restricted keys, rate limits you suddenly tripped, misconfigured webhook secrets, and IP restrictions are all problems on your side. Stripe's status page cannot see them, because they are not Stripe's problem. They are still your outage.

This is the same class of silent failure we cover in detail in why uptime monitors miss real outages. The only reliable way to know Stripe is working for your customers is to test it yourself, on a short interval, and assert on the response body.

Stripe Status Page vs. Your Own Monitor: Side by Side

Here is the honest comparison between relying on status.stripe.com and running your own Velprove monitor on the free plan. Both are free. Only one of them tells you the truth on your schedule.

What About Stripe Webhooks or the Stripe Dashboard?

Two other tools get proposed all the time as a substitute for real Stripe monitoring. Both are useful. Neither is a monitoring system, and it is worth being clear about why.

Stripe webhooks tell you that a specific event has happened, after the fact. A successful charge, a failed charge, a disputed payment, a refund. What webhooks cannot tell you is that the API is unreachable, that your webhook endpoint itself has stopped responding, or that the checkout page never loaded in the first place. If Stripe is down, you receive zero webhooks, which is indistinguishable from a quiet Tuesday. Webhooks are essential for business logic. They are useless as an outage alarm. If you also need to validate that your webhook handler itself is up, see our companion guide on how to monitor your Stripe webhook pipeline end-to-end.

The Stripe dashboard is excellent for after-the-fact analysis. You can watch payment volumes, inspect specific charges, and review API logs. What it cannot do is page you when something breaks. It requires a human to be looking at it, and the human is almost never looking at it at 3 AM when the real incident starts. Dashboards are retrospective by design.

A proactive external monitor is the only tool that answers the question "is Stripe working for my customers right now" on a schedule, without requiring anyone to be paying attention. That is the job Velprove does.

Setting Up a Stripe API Health Monitor With Velprove

Velprove's API monitor type lets you monitor Stripe by making a real API call and validating the response, not just the status code, but the actual JSON body. The full setup takes about five minutes. Here is how to do it.

Step 1: Pick a safe, read-only endpoint

The best endpoint for health monitoring is the Balance endpoint, GET https://api.stripe.com/v1/balance. This endpoint is read-only, does not create any objects, does not generate fees, returns a small predictable JSON body, and is available in both test and live mode. It is ideal for automated health checks, and it is the same endpoint Stripe's own internal probes use as a smoke test.

Avoid using write endpoints like PaymentIntents, Charges, or Customers for monitoring. Even in test mode, they create real objects that clutter your dashboard and make debugging harder. A read-only monitor is always the right call.

Step 2: Try the endpoint from your own terminal first

Before wiring up any monitoring tool, confirm the request works by running it yourself. This is the exact request Velprove will send under the hood. Replace the key with a restricted key from your Stripe dashboard.

curl -X GET https://api.stripe.com/v1/balance \
  -H "Authorization: Bearer rk_live_your_restricted_key" \
  -H "Stripe-Version: 2024-11-20.acacia"

A healthy response looks like this. The exact currency amounts will differ for your account, but the top-level structure is stable.

{
  "object": "balance",
  "available": [
    { "amount": 125430, "currency": "usd", "source_types": { "card": 125430 } }
  ],
  "connect_reserved": [],
  "livemode": true,
  "pending": [
    { "amount": 48200, "currency": "usd", "source_types": { "card": 48200 } }
  ]
}

The field your monitor is going to assert on is object, which is always the literal string balance on this endpoint. That is the anchor that tells you the response is a real Stripe balance payload and not an error object dressed up with a 200 status code.

Step 3: Create an API monitor in Velprove

Sign up for a free Velprove account and create a new monitor. Choose API monitor as the type, set the method to GET, and the URL to https://api.stripe.com/v1/balance. Give it a clear name like "Stripe API health" so it is easy to spot in your monitor list and in alert emails.

Step 4: Configure authentication with a restricted key

Add an Authorization header with the value Bearer rk_live_your_restricted_key. Do not use your root secret key. In your Stripe dashboard, go to Developers, API keys, and click Create restricted key. Grant only the Balance resource with Read permission, and explicitly set every other resource to None. A leaked restricted key with only Balance read cannot create charges, issue refunds, read customer PII, or change anything on your account. That is the principle of least privilege applied to monitoring credentials.

This same least-privilege pattern is the backbone of safe authenticated monitoring. For a deeper walkthrough of monitoring token-based auth flows, see our guide on monitoring multi-step API authentication flows.

Step 5: Add JSON path validation

This is where Velprove goes beyond basic status code monitoring. Configure a JSON path assertion to validate that the response contains the expected data.

• JSON path: $.object
• Operator: equals
• Expected value: balance

This confirms that Stripe is not just responding, but returning a real balance object. If the API returns an error payload, a rate limit message, or an authentication failure, the JSON path will not match and the monitor will fail, which is exactly what you want. For the general pattern, see our guide to monitoring REST API health endpoints with response validation.

If you want extra confidence, add a second assertion on $.livemode equal to true when you are using a live key. That way a monitor accidentally pointed at a test key will fail loudly instead of silently watching the wrong environment.

Step 6: Set interval and alerts

On the free plan, your Stripe monitor runs every 5 minutes and emails you when the JSON path assertion stops matching. That is the entire configuration. No credit card, no paid tier, no trial clock. Make sure the email address on your Velprove account is one you actually read at 3 AM, or forward Velprove alerts to your on-call inbox at the mail-server level. Velprove's free plan includes 10 monitors, which is plenty to cover a Stripe API monitor, an HTTP monitor on your own checkout page, and the core routes of your production stack.

A Worked Example: 5-Minute Detection vs. 30-Minute Status Page Lag

To make the lead-time argument concrete, here is the same Stripe incident viewed through two different monitoring setups. Assume a real degradation starts at 14:00:00 UTC, where the PaymentIntents endpoint begins returning intermittent HTTP 500 responses.

• 14:00:00. First customer hits a failed charge. Their card was not billed. They stare at a generic error and either retry or leave.
• 14:02:30. Velprove free-plan monitor (5-minute interval) fires a scheduled GET /v1/balance, gets a 503, fails its JSON path assertion, and queues an email alert.
• 14:03:00. Email hits your inbox and your team chat is pinged. You are roughly 3 minutes into the incident.
• 14:05:00. You deploy a banner to the checkout page warning customers that payments are delayed. New visitors see the warning and hold off, instead of burning retries.
• 14:18:00. Stripe's internal incident review completes and status.stripe.com turns yellow. 18 minutes after the incident began.

In the status-page-only scenario, those 15 plus minutes between 14:00 and 14:18 are a pure loss. Every visitor who tried to check out saw a generic failure, lost trust, and either retried on a competitor or filed a support ticket you will spend the next week answering. With a 5-minute API monitor, that window shrinks to about 3 minutes before you know, and the only customers who see any failure at all are the handful who hit the broken endpoint before your banner went up.

Monitoring the Full Checkout Flow With Multi-Step Monitors

A single GET /v1/balance monitor is the bare minimum for Stripe health. It tells you the API is answering and your credentials work. It does not tell you that your actual checkout flow, the sequence of API calls your application makes when a real customer clicks Pay, still succeeds end to end.

Velprove's multi-step API monitor lets you chain several API calls in order, pass values between them, and assert on the response of each step. For a SaaS checkout, a realistic chain looks like this.

1. Step 1. POST /v1/customers with a test email. Assert the response has $.object equal to customer. Capture the customer id.
2. Step 2. POST /v1/payment_intents with the captured customer id, a test amount, and automatic_payment_methods enabled. Assert $.status equals requires_payment_method.
3. Step 3. GET /v1/payment_intents/{id}with the captured payment intent id. Assert the retrieve call returns the same status.

If any single step fails, the full monitor fails and alerts you with the specific step and the response body. This catches the class of failures a single-endpoint monitor cannot: an API version mismatch that only breaks the create call, a permissions issue on payment_intents that leaves balanceworking fine, a regional slowdown that affects one endpoint but not another. If you run this in test mode against test keys, it costs you nothing and creates no real objects. Velprove's free plan caps multi-step monitors at 3 steps, which is exactly enough for this chain. For the full chaining pattern, see our multi-step API monitoring guide.

Monitor Your Own Checkout Page With an HTTP Content Assertion

API monitors are necessary but not sufficient. They tell you the Stripe API is answering, but they do not tell you your customers can actually get to a working card form. Stripe.js can fail to load. Your publishable key can get rotated. A new Content Security Policy can quietly block Stripe domains. A routing change can leave your checkout page 404ing while the Stripe API stays green. The API monitor stays passing. Your checkout stays broken.

The simplest way to catch this class of failure is to add a second Velprove monitor, this time an HTTP monitor pointed at your own checkout page URL. Configure a content assertion that checks the response body contains a string only present when Stripe.js is wired up correctly, for example js.stripe.com or your publishable key prefix pk_live_. If a deploy, a CSP change, or a broken route ever removes that string from the page, the HTTP monitor fails and you hear about it long before a paying customer does.

If you run a SaaS product, pair an API monitor on /v1/balance, a multi-step monitor on your payment creation chain, and an HTTP content assertion on your own checkout page. That stack is genuinely free and covers the three distinct failure surfaces of a Stripe integration. Our SaaS monitoring page walks through the full pattern for founders shipping checkout-dependent products.

Stripe API Monitoring Errors: 401, 429, 500, and Timeout Explained

When your Stripe health monitor fails, the cause is not always a platform outage on Stripe's side. Triage is faster if you know the four most common failure modes and what each one means for your response.

• Authentication error (HTTP 401). Your API key was rotated, the restricted key was deleted, or its permissions were narrowed and Balance read was removed. Check your Stripe dashboard under Developers, API keys, and verify the key is still active and still has Balance read permission. This is not a Stripe outage. It is a key management issue, and it is fully on your side.
• Rate limit exceeded (HTTP 429). You are making too many API calls. In practice this is almost never the monitor itself. A 5-minute monitor uses roughly 0.003 requests per second against a 100-per-second read budget. The real culprit is usually a background job or a webhook retry loop hammering Stripe. Pull up your Stripe API logs, filter on 429s, and look at the calling IP and endpoint. For a deeper view of Stripe rate limit patterns, the Stripe dashboard logs view is your friend.
• Server error (HTTP 500 or 503). This is the one most likely to be a genuine Stripe issue. Cross reference with status.stripe.com (knowing it will lag you), check Stripe community reports, and start your incident response. There is nothing to fix on your end, but you can and should proactively notify your customers and your support team.
• Timeout with no response. The request took longer than your timeout threshold. This could mean Stripe degradation, a network issue between your monitoring region and Stripe's edge, or packet loss upstream. Intermittent timeouts are worth treating as a warning sign of incoming degradation, especially if they cluster.

What to Do With Your Lead Time

Early detection is only useful if you have a plan for how to spend the time it buys you. Here is the playbook we recommend for the 10 to 20 minute head start a proper Stripe health monitor gives you over the public status page.

• Deploy a checkout banner immediately. A single line of copy like "We are seeing elevated payment processing delays. Your card has not been charged. Please retry in a few minutes." is dramatically better than the generic error page your customers would otherwise see.
• Flip to a backup payment processor if you have one. Larger merchants often keep a second processor configured as a fallback. This is the moment to use it.
• Notify your support team. A two-line message to the support channel saves you from a tidal wave of confused tickets and lets agents respond with confidence.
• Update your own status page. Get ahead of the narrative. Customers who see a proactive status update trust you more after an incident, not less.
• Pause automated retries. If you have dunning logic or subscription retry jobs, pausing them prevents burning through customer retry budgets on a degraded Stripe API.

The difference between a professional incident response and a panicked scramble is almost always just early detection. A free API monitor with a 5-minute interval and real JSON validation is the cheapest way to buy that edge.

Frequently Asked Questions

How do I monitor Stripe API uptime for free?

Create a free Velprove account, add an API monitor that sends a GET request to https://api.stripe.com/v1/balance with a restricted Stripe secret key in the Authorization header, and add a JSON path assertion on $.object equal to balance. The free plan runs the monitor every 5 minutes and emails you when the response stops matching. That is a full Stripe uptime monitor with real response validation, at no cost.

Is the Stripe status page a reliable way to know Stripe is down?

No. Stripe's status page at status.stripe.com is a communication tool, not a monitoring tool. It is updated manually after an incident is confirmed internally, and that process commonly lags real customer impact by 10 to 30 minutes. Partial degradation, regional slowdowns, and account-level issues like expired API keys or rate limits never appear on it at all. The only reliable signal is to make a real API call yourself on a short interval and validate the JSON response.

Do Stripe webhooks replace uptime monitoring?

No. Webhooks tell you after the fact that a specific event happened. They cannot tell you that the API is unreachable, that your key was rotated, or that the checkout page has stopped loading. If Stripe is down, you will receive zero webhooks, which is indistinguishable from a quiet Tuesday. A proactive monitor that calls the API on a schedule and validates the JSON response is the only way to know the system is healthy right now.

Which Stripe API endpoint is safest to use for health monitoring?

The Balance endpoint, GET https://api.stripe.com/v1/balance, is the safest and most widely recommended choice. It is read-only, it does not create or mutate any objects, it does not generate fees, it is available in both test and live mode, and it returns a small predictable JSON body with $.object equal to balance. Avoid POST endpoints like PaymentIntents for health checks because they create real objects and pollute your dashboard.

What are Stripe API rate limits and will monitoring hit them?

Stripe's documented rate limits are 100 read requests per second in live mode and 25 per second in test mode, with burst allowances above that. A health monitor hitting GET /v1/balance once every 5 minutes uses about 0.003 requests per second, which is a rounding error against the live-mode read quota. You will never hit the rate limit from monitoring alone. If you do see HTTP 429 responses, the cause is almost always other application traffic, not the monitor.

How fast can Velprove detect a Stripe outage on the free plan?

The free plan runs your Stripe API monitor every 5 minutes, so the worst-case detection window between a Stripe incident starting and Velprove firing an email alert is about 5 minutes. Compared to the 15 to 30 minute lag typical of status.stripe.com, that is a 3x to 6x head start. On a 5-minute interval, you are almost always the first person in your company to know something is wrong, instead of the last.

Should I use a restricted API key for Stripe monitoring?

Yes, always. In your Stripe dashboard under Developers, API keys, click Create restricted key and grant only the Balance resource with Read permission. Every other resource should be set to None. A leaked restricted key with Balance read only cannot create charges, refund payments, read customer PII, or modify anything. This follows the principle of least privilege and dramatically reduces blast radius if the key is ever exposed.

Can Velprove catch Stripe.js failing to load on my checkout page?

Yes. You add a second Velprove monitor, an HTTP monitor pointed at your own checkout page URL, and configure a content assertion that the response body contains a string only present when Stripe.js is wired up correctly, such as js.stripe.com or your publishable key prefix pk_live_. If a deploy, a CSP change, or a broken route ever removes that string from the page, the HTTP monitor fails and alerts you before a real customer does. This is the free-plan way to monitor the checkout page itself alongside the Stripe API.

What JSON path assertion should I use on the Stripe balance response?

Use JSON path $.object with expected value balance. The Stripe balance response always has an object field at the root set to the string balance, so this assertion is stable across API versions and account states. For extra confidence you can add a second assertion on $.livemode equal to true (for live keys) or check that $.available is present as an array. Do not assert on specific currency amounts because those change constantly.

Start Monitoring Stripe in Minutes

Your customers trust you to handle their payments. When that trust breaks, whether it is a real Stripe outage, a rotated API key, or a rate limit you did not expect, you should be the first to know. Not your customers. Not your support inbox. Not a yellow banner on a status page 20 minutes after the fact.

Set up a free Stripe API health monitor with Velprove in about five minutes and stop relying on status pages to tell you when your payments are broken. If you run a SaaS product and want to cover the full Stripe surface, including your checkout page and your payment creation flow, our SaaS monitoring page walks through the full pattern end to end.