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.
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
HS_VALIDATION_ERROR | 400 | The 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_REQUEST | 400 | Invalid request (format, parameter). | Fix the request format. |
HS_UNAUTHENTICATED | 401 | Session cookie or Authorization: Bearer hs_live_… is missing/invalid. | Check your API key; sign in to the dashboard again. |
HS_FORBIDDEN | 403 | Role 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_MISMATCH | 403 | Reserved 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_FOUND | 404 | The resource does not exist or you have no access to it (existence is not leaked). | Check the ID and the tenant context. |
HS_CONFLICT | 409 | Uniqueness conflict (slug, email, alias). | Use a different value. |
HS_IDEMPOTENCY_CONFLICT | 409 | The same idempotency_key was used with a different body. | Generate a new key or send the same body. |
HS_IDEMPOTENCY_IN_PROGRESS | 409 | A request with the same key is still being processed. | Retry the same request shortly. |
HS_NO_RECIPIENTS | 422 | The target audience is empty (no matching active subscription). | Check the targeting and the channel configuration. |
HS_CHANNEL_NOT_CONFIGURED | 422 | The channel credential is missing or inactive. | Configure and verify it under Dashboard → Channels. |
HS_CONTENT_INVALID | 422 | Content rules were violated (length, URL, Liquid). | Fix the content. |
HS_SUBSCRIPTION_INVALID | 422 | The subscription is not active. | Wait for the device to re-register. |
HS_UNPROCESSABLE | 422 | The request cannot be processed semantically. | See the message field. |
HS_RATE_LIMITED | 429 | Rate limit exceeded; a Retry-After header is returned. | Wait for the indicated time and retry (the SDKs do this automatically). |
HS_QUOTA_EXCEEDED | 429 | Plan quota exceeded. | Upgrade your plan or wait for the quota to reset. |
HS_PLAN_FEATURE_REQUIRED | 403 | The feature is not available on the current plan (details.feature, details.plan). | Upgrade your plan (Billing). |
HS_ORG_SUSPENDED | 403 | The organization is suspended (details.reason); only billing is readable. | Fix billing or contact support. |
HS_SUPPORT_READ_ONLY | 403 | A platform support session is read-only. | An organization member must make the change. |
HS_SSO_REQUIRED | 403 | The 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_INTERNAL | 500 | Unexpected error. | Open a support request with the request_id. |
HS_NOT_IMPLEMENTED | 501 | The 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_UNAVAILABLE | 503 | The push provider is temporarily not responding. | Retry; deliveries are retried automatically by the worker. |
HS_SERVICE_UNAVAILABLE | 503 | The service is temporarily unavailable (maintenance, dependency). | Check the /readyz status and retry. |
Retry rules
- Server SDKs (
@pushizo/node,pushizo/pushizo-php) retry429and5xxresponses with exponential backoff;4xxis 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(seedocs/plan/05).
Webhooks
Pushizo delivers events from your app (deliveries, opens, subscriptions, users, events, conversions, campaigns) to your server over HTTPS, signed. Endpoints are managed in the dashboard under Developer → Webhooks or…
Security overview
The Pushizo security model — authentication, RBAC, tenant isolation (RLS), secret encryption, application security (SSRF, CSP, signatures), observability and audit logging; ASVS checklist.