API monitoring: when HTTP 200 is not enough

A JSON API can return HTTP 200 with an error in the body - status-code monitoring declares it UP. Real API monitoring also checks the response content, not just HTTP.

The problem: HTTP 200 != a working API

According to REST API conventions, status codes should be used correctly (200 OK, 4xx client error, 5xx server error). In practice:

Some APIs always return 200, with the error in the JSON body
An API gateway can transform a 5xx into a 200 with error JSON
Frontend BFF endpoints often wrap backends and return 200 if the communication succeeded, even when the backend failed
GraphQL endpoints typically return 200; errors live in the errors[] array

From the perspective of classic monitoring (HTTP status code), everything is fine. From the perspective of a real client, the API is broken.

Content matching: keywords

The simplest add-on to HTTP monitoring is a keyword match. You define a string that must be present in the response - if it is missing, an alert is sent.

Example for a health check endpoint:

GET /api/health HTTP/1.1

{
  "status": "ok",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "queue": "ok"
  },
  "version": "1.42.3"
}

Set the keyword match to "status":"ok". If the DB goes down and the endpoint returns "status":"degraded", the monitoring catches it.

Negative matching: what should be absent

Sometimes it is more useful to check that a certain string is NOT in the response:

"error" - an error in the body
"maintenance" - an unexpected maintenance mode
"deprecated" - the API endpoint has been marked as deprecated
SQL error fragments: "SyntaxError", "undefined", "null pointer" - leaking backend errors

Advanced assertions

Plain text matching has its limits. For serious API monitoring, structured assertions over the JSON structure (JSONPath expressions) and multi-step synthetic transactions (login -> protected endpoint -> logout) are the right tool.

ePulz.io supports these options directly. Multi-step / API monitoring lets you chain up to 10 steps (GET/POST/PUT/PATCH/DELETE/HEAD), validate the status code, content and a JSONPath value at each step, and store variables from the response for subsequent steps. The feature is available on the Profi and Business plans and runs on the primary region. For simpler cases on lower plans, you can combine an HTTP monitor with a separate helper script that sends the result via a heartbeat monitor.

Authentication in monitoring

A monitored endpoint often requires auth. Options:

Bearer token in the Authorization header - typically a long-lived monitoring token with no expiry (store it securely)
API key in a query parameter - visible in logs, not preferred
HMAC signature - timestamp + URL + body hash signed with a shared secret. The most secure.
mTLS - a client cert on the monitoring side. Suitable for internal APIs.

Security note: For monitoring, create a dedicated account / token with minimal permissions (read-only health endpoint, not an admin token). Rotate the token regularly. If the monitoring service is compromised, it will not leak full access to the API.

Response time SLO

API response time is just as important as the HTTP code. A client with a 30 s timeout sees no difference between "the API returns 200 in 25 s" and "the API hit a timeout". From a UX point of view, both are bad.

Set:

Hard timeout - after 10-15 s the monitoring reports DOWN
Soft threshold - a response time between 500-2000 ms = warning (degraded performance)
Trend alerts - an alert if the 95th percentile of response time rises by 50 % over the last 24 h

Per-endpoint monitoring

A large API has dozens of endpoints. Do not monitor only /health - even that can lie. Identify 3-5 critical endpoints:

The most-used business operations (POST /api/orders, GET /api/dashboard)
A read endpoint testing a cache hit (fast response)
A write endpoint with a DB roundtrip
An external integration endpoint (calls a third party - detects dependency outages)

Monitor each one separately. During an incident you then see exactly which part of the API went down.

Conclusion

API monitoring cannot be reduced to an HTTP status code. Quality monitoring combines status + content match + response time + per-endpoint granularity + authentication, so it faithfully mimics a real client - not just an HTTP client.

API monitoring with keyword matching

Status code + keyword in content + response time + auth headers. Per-endpoint granularity.

Start monitoring →