Skip to content
NovaVMS Manual

API error code reference

API error code reference

Every error response from the NovaVMS API has a stable error string. This page lists every one, grouped by HTTP status. Match the error value from the response body (not the HTTP status alone) — status codes overlap across causes.

All errors share this shape:

{
  "error": "validation_failed",
  "message": "Human-readable detail",
  "request_id": "req_01HK3Z..."
}

The error string is the stable contract. Code against that. The message field is for humans and may change between releases.

4xx — client errors

Error stringHTTPMeaningHow to fix
auth_required401No credential was sent, or the session cookie is missing.Send the session cookie (web) or Authorization: Bearer <token> header (mobile/API). See auth how-to.
invalid_token401The token is malformed, expired, or signed by a different key.Refresh the token. If refresh also fails, re-authenticate.
forbidden403The caller is authenticated but lacks permission for this resource, or the resource belongs to a different org.Check the caller’s role and the target resource’s org_id. See roles and permissions.
not_found404The resource does not exist, or exists in another org.Confirm the ID and that the caller’s org owns it. NovaVMS returns 404 (not 403) when cross-org access is attempted, to avoid leaking existence.
validation_failed400One or more fields failed validation. The message lists the first failing field.Fix the input per the field constraints documented in the endpoint’s reference page.
conflict409The request conflicts with current state (duplicate name, version mismatch on optimistic concurrency, etc.).Re-fetch the resource and retry with fresh state.
rate_limited429The caller exceeded the per-token rate limit.Read the Retry-After header and back off. See rate limit handling.
webhook_signature_invalid400Webhook receiver returned a signature-verification error, or the test-webhook endpoint could not verify your shared secret.Re-check the secret. See webhook signing.
webhook_endpoint_unreachable400The webhook URL is not reachable over TLS.Confirm the endpoint is public, serves a valid certificate, and returns 2xx to a POST /.

5xx — server errors

Error stringHTTPMeaningHow to fix
internal_error500Unhandled server-side error. request_id is always set.Retry with exponential backoff. If the error persists, provide the request_id to support. See request tracing.
service_unavailable503A downstream dependency (database, AI provider, storage) is temporarily unavailable.Retry with exponential backoff. Status page at https://status.novalien.com.
webhook_delivery_failed502NovaVMS attempted to deliver a webhook to your endpoint and received a non-2xx or timed out. Applies to the outbound side.See webhook delivery failures.

See also