PushizoDocs

Error catalog

All API errors are returned in the same envelope (packages/shared/src/errors.ts):

All API errors are returned in the same envelope (packages/shared/src/errors.ts):

{
  "error": {
    "code": "HS_VALIDATION_ERROR",
    "message": "The request could not be validated.",
    "details": { "issues": [{ "path": "contents", "message": "Required" }] },
    "request_id": "req_01…",
    "doc_url": "https://docs.pushizo.com/errors#HS_VALIDATION_ERROR"
  }
}

The request_id value matches the response's x-request-id header; you can search for it in support requests and on the Logs screen. For Public API requests, the error code is also returned in the x-hs-error-code header.

CodeHTTPMeaningWhat to do
HS_VALIDATION_ERROR400The body/query does not match the schema; details.issues carries a per-field list.Compare your request with the schema in api/openapi.yaml.
HS_BAD_REQUEST400Invalid request (format, parameter).Fix the request format.
HS_UNAUTHENTICATED401Session cookie or Authorization: Bearer hs_live_… is missing/invalid.Check your API key; sign in to the dashboard again.
HS_FORBIDDEN403Role permission, API key scope, CSRF, org MFA requirement (details.reason = mfa_required) or IP allowlist (ip_not_allowed).Obtain the relevant permission/scope; set up MFA; have your IP added to the list.
HS_TENANT_MISMATCH403Reserved code; the API does not emit it. Access to another tenant's resource returns 404 HS_NOT_FOUND so existence is not leaked (ADR-0011).—
HS_NOT_FOUND404The resource does not exist or you have no access to it (existence is not leaked).Check the ID and the tenant context.
HS_CONFLICT409Uniqueness conflict (slug, email, alias).Use a different value.
HS_IDEMPOTENCY_CONFLICT409The same idempotency_key was used with a different body.Generate a new key or send the same body.
HS_IDEMPOTENCY_IN_PROGRESS409A request with the same key is still being processed.Retry the same request shortly.
HS_NO_RECIPIENTS422The target audience is empty (no matching active subscription).Check the targeting and the channel configuration.
HS_CHANNEL_NOT_CONFIGURED422The channel credential is missing or inactive.Configure and verify it under Dashboard → Channels.
HS_CONTENT_INVALID422Content rules were violated (length, URL, Liquid).Fix the content.
HS_SUBSCRIPTION_INVALID422The subscription is not active.Wait for the device to re-register.
HS_UNPROCESSABLE422The request cannot be processed semantically.See the message field.
HS_RATE_LIMITED429Rate limit exceeded; a Retry-After header is returned.Wait for the indicated time and retry (the SDKs do this automatically).
HS_QUOTA_EXCEEDED429Plan quota exceeded.Upgrade your plan or wait for the quota to reset.
HS_PLAN_FEATURE_REQUIRED403The feature is not available on the current plan (details.feature, details.plan).Upgrade your plan (Billing).
HS_ORG_SUSPENDED403The organization is suspended (details.reason); only billing is readable.Fix billing or contact support.
HS_SUPPORT_READ_ONLY403A platform support session is read-only.An organization member must make the change.
HS_SSO_REQUIRED403The organization uses "SSO only"; the session was not opened with SSO for this organization (details.org_id).Use Sign in with enterprise SSO on the sign-in screen; the owner can sign in with an SSO recovery code.
HS_INTERNAL500Unexpected error.Open a support request with the request_id.
HS_NOT_IMPLEMENTED501The feature is not available in this version (segment targeting, templates, time-zone delivery — Phase 7).Use the supported alternative (the message field suggests one).
HS_PROVIDER_UNAVAILABLE503The push provider is temporarily not responding.Retry; deliveries are retried automatically by the worker.
HS_SERVICE_UNAVAILABLE503The service is temporarily unavailable (maintenance, dependency).Check the /readyz status and retry.

Retry rules

  • Server SDKs (@pushizo/node, pushizo/pushizo-php) retry 429 and 5xx responses with exponential backoff; 4xx is not retried.
  • Client SDKs queue operations on the device when offline or on 5xx.
  • On the delivery side, transient provider errors are retried on a 30 s / 2 min / 10 min / 30 min / 2 h schedule; an invalid token marks the subscription invalid (see docs/plan/05).

On this page