Errors & limits
Error codes
HTTP status codes returned by the Obzerv API and what they mean.
All errors come back as JSON with an error field carrying both a stable prefix and a trailing detail in a single string:
{ "error": "Validation failed: name is required" }Match the prefix (Validation failed, Unauthorized, Plan limit reached, etc.) when branching on error type — the prefix list below is the public contract; the trailing detail is human-readable and may be refined.
Status codes
| Code | Meaning | Common causes |
|---|---|---|
400 | Validation error | Body failed Zod schema validation. details.issues lists the failing fields. |
401 | Missing or invalid API key | No Authorization header, malformed key, or key was revoked. |
403 | Plan does not allow this action | Hit a plan limit (monitor count, region count, business-only feature). |
404 | Resource not found | Wrong id, or the resource belongs to a different account. Obzerv returns 404 instead of 403 to avoid leaking existence. |
409 | Conflict | Slug already taken (status pages), or unique constraint violation. |
422 | Unprocessable | Schema-valid but business-invalid (e.g. monitor URL points at private IP). |
429 | Rate limit exceeded | More than 60 req/min/IP/endpoint. Retry-After header included. See rate limits. |
500 | Internal server error | Bug — please report at support@obzerv.xyz with the timestamp of the failing call. |
503 | Temporarily unavailable | Background workers backed up. Retry with exponential backoff. |
Common error prefixes
The following prefixes are stable across releases — safe to match in if (error.startsWith(...)) checks:
Validation failedUnauthorizedPlan limit reachedThe <type> alert channel requires a higher planNot foundSlug already taken(conflict on status pages)Rate limit exceededInternal error
Reporting issues
Email support@obzerv.xyz with the failing endpoint, the exact request body, the response, and the timestamp of the call.