API error codes
Complete catalog of error codes returned by the HowlOps REST API.
Error responses carry a lowercase error string, and sometimes a code field:
json
{
"error": "forbidden",
"code": "INTERNAL"
}
The error value is a lowercase machine-readable string (for example forbidden, monitor_not_found, internal_error). Most errors return only error; a subset also include a short uppercase code (for example INTERNAL). There is no nested details object.
Common error strings
error value | HTTP status | Meaning |
|---|---|---|
unauthorized | 401 | Missing, expired, or invalid authentication credential. |
forbidden | 403 | Authenticated but lacking the required role or permission for this action. |
csrf_token_invalid | 403 | The X-CSRF-Token header is missing or incorrect on a session-authenticated unsafe request (POST/PUT/PATCH/DELETE). |
<resource>_not_found (for example monitor_not_found) | 404 | Resource does not exist, or you do not have permission to see it (IDOR returns 404, not 403). |
conflict | 409 | Duplicate resource or conflicting state transition. |
mfa_already_enabled | 409 | MFA setup was attempted while MFA is already active on the account. |
last_auth_method | 409 | Attempting to unlink the last remaining sign-in method is not allowed. |
validation_failed | 422 | Request body failed field validation. |
mfa_code_invalid | 401 (login) / 422 (setup verify) | Provided TOTP or backup code is incorrect or already used. MFA login returns 401; MFA setup verify returns 422. |
rate_limited | 429 | Too many requests. See the Retry-After header for the window reset time. |
tier_limit_exceeded | 422 | The action would exceed a numerical limit (e.g. monitor count) for the capability plan that gates it. |
tier_feature_not_available | 422 | The feature requires a higher plan on the relevant capability (Uptime, On-call, or Status pages). |
email_not_verified | 403 | Account email address has not been verified. Check inbox or request a new verification email. |
mfa_required | 200 | Login succeeded for the first factor but a TOTP or backup code is still required. Response body carries mfa_required: true and a session token for the second step. |
invalid_grant | 400 | OAuth token/refresh endpoint: the authorization code is invalid, expired, or already used (RFC 6749 format). |
internal_error | 500 | Unexpected server error (returned with code: "INTERNAL"). Include the X-Request-Id header value when reporting. |
Tier/feature-gate errors (tier_limit_exceeded, tier_feature_not_available) are returned as 422. A few endpoints (for example SSO) return a raw HTTP 402 Payment Required when a paid plan is needed; those bare 402 responses carry a human-readable error message.
Rate limit endpoints
| Endpoint group | Limit | Window |
|---|---|---|
/api/v1/auth/* (login, register, reset, verify) | 30 requests | 1 minute / IP |
/api/v1/oauth/* (token, refresh) | 30 requests | 1 minute / IP (shares the auth limiter) |
/api/v1/hb/* (heartbeat pings) | Configurable per tenant | n/a |
| Default (authenticated) | 600 requests | 1 minute / user (all plans) |
Public reads (/api/v1/public/*) | 300 requests | 1 minute / IP |
See also
Was this page helpful?