API monitoring checklist for assertions, timeouts and auth

The best monitored endpoint is the one whose failure someone would notice. Begin with the calls that sit on revenue and trust paths, then add calls that reveal the health of shared dependencies. A health endpoint alone is not enough, because it often answers even when the database, cache or queue behind real requests is down.

• Authentication or token exchange, because every other call depends on it
• The read call your main product screen or mobile app makes on load
• Search or listing calls that hit the database with real queries
• Checkout, billing or order status calls, monitored read-only
• Public endpoints partners integrate with, including webhook receivers
• One call per major dependency, such as a call that reads from the cache or calls a downstream service
• The documented health endpoint, kept as a fast baseline

If clients still call version 1 while you build version 3, both are production. Older versions often run on code that changes rarely and gets tested less, which makes them more likely to break silently when shared infrastructure changes. Add one monitor per supported version for the calls clients rely on most, and retire it when the version is retired.

A monitor that sends a bare request without the headers a real client sends can pass while real clients fail, or fail while real clients pass. Match the request to production traffic.

• Use the same HTTP method clients use
• Send the Accept and Content-Type headers your API expects
• Include an API version header if your routing depends on one
• Set a clear User-Agent so the monitor is easy to find in logs and to allow through rate limits
• For POST queries that only read data, such as search, send a realistic body
• Avoid hidden caching by adding the same cache headers clients use, so you are not only testing a cached copy

Monitoring needs to authenticate like a client, and that credential lives in a third party system. Treat it accordingly. Create a dedicated monitoring account or token that can only read the data the checks need. It should not be able to write, delete, change settings or read other customers' data. If the token leaks, the worst outcome should be that someone can read a test record.

• Create a separate service account for monitoring, never reuse a person's credentials
• Grant read-only scope on the specific resources the checks call
• Point checks at a dedicated test tenant or test record where possible
• Name the token clearly so it is easy to find and revoke
• Store it only in the monitoring tool, not in scripts or shared documents

Tokens with an expiry date will eventually turn every check red at the same moment. That outage is not real, but it still wakes someone up and teaches the team to ignore alerts. Put the monitoring token's expiry date in the same calendar as certificate expiry. Rotate it on a schedule: create the new token, update the monitors, confirm one full check cycle passes, then revoke the old token. If your auth flow issues short lived access tokens, monitor the token exchange call itself, so a broken login shows up as its own alert.

Assert the exact status code you expect, not a range. A 204 where you expect 200, or a 302 to a login page where you expect 200, is a failure worth knowing about. Decide how to treat redirects: an API that suddenly redirects is usually misconfigured, so most API checks should not follow redirects silently.

Body assertions turn a reachability check into a correctness check. Keep them stable: assert on structure and on values that should never change, not on values that change every minute.

• The response is valid JSON and has the expected top level type
• A required field exists, such as an id or a status field
• A field has a known value, such as status equal to "ok" on a health call
• An array is not empty when it should never be empty, such as a list of plans
• An error field is absent
• Numeric values sit inside a sane range, such as a price above zero

Avoid asserting on timestamps, counters or anything personalized. Those assertions fail on normal data changes and produce noise. A small set of strong assertions beats a long brittle list.

A single slow response is rarely an incident. A pattern of slow responses usually is. Look at the normal response time of each endpoint over a week, then set a warning threshold above the usual p95 and a timeout well above the p99. A search call with a p95 of 400 ms might get a warning at 1.5 s and a timeout at 10 s. A health endpoint with a p95 of 50 ms might warn at 500 ms and time out at 5 s.

A request that hangs for 60 seconds is worse for clients than one that fails in one second, because clients hold connections and threads while they wait. If your monitor waits forever, it reports late or never. A timeout close to what your real clients tolerate makes the monitor fail at the same point your users do.

Some of the most important calls create things: orders, signups, payments, messages. Monitoring them directly from outside creates real records every minute, triggers emails and can distort business metrics. There are safer options.

• Monitor the read side of the flow, such as order status for a known test order
• Use a dedicated test tenant where writes go to an isolated account
• Expose a dry run or validation mode that runs checks without committing
• Chain a create and a delete in one sequence only in a test tenant, never on real customer data
• Monitor background workers that process writes with a heartbeat that pings after each successful batch

Monitors count against rate limits like any client. A check every 30 seconds is 120 requests an hour per endpoint, and five endpoints checked from two regions add up to 1,200 requests an hour. That is small for most APIs but can matter for strict per token limits. Give the monitoring token its own quota or allow list it, and assert that responses are not 429. A rate limit triggered by real traffic should show up as a separate, clearly labeled failure.

Your API depends on payment processors, identity providers, email senders and internal services. When one of them fails, your endpoint may still return 200 with degraded data. Add one assertion per dependency where the response shows it, such as a field that is only filled when a downstream call succeeds. You can also monitor the third party's public status or health endpoints directly, so you can tell in seconds whether a failure starts with you or with them.

• Group monitors by service or team so alerts go to the owning team
• Route auth and token exchange failures as high priority, because they break everything downstream
• Send response time warnings to a team channel during working hours, not to a phone at night
• Send hard failures, confirmed from a second region, through the on-call path
• Escalate to a second person if nobody acknowledges within a set number of minutes
• Mute checks during planned deploys and migrations with maintenance windows
• Include the endpoint, the assertion that failed and the response snippet in the alert, so the first responder does not have to reproduce it

UptimePilot runs API checks with method, headers, body and JSON assertions on every plan, confirms failures from a second region and alerts by email, SMS, Slack, Microsoft Teams or webhook with escalation. Read how api monitoring works, chain requests with assertions using synthetic monitoring, track background jobs with cron job monitoring, watch latency trends with website performance monitoring, and compare plans on uptime monitoring pricing.