Troubleshooting Guide

401 Unauthorized — "api key required"

Pass your API key in the request header. Use X-API-Key: ps_your_key or Authorization: Bearer ps_your_key.

403 Forbidden — email not yet verified

Click the verification link in your welcome email. Haven't received it? Use POST /api/resend-verification with your email, or check spam. The link expires after 72 hours.

400 Bad Request — invalid BPMN

Every BPMN process must have at least one End Event. Open your model in Camunda Modeler, fix the validation errors shown in the lower panel, then re-export and redeploy.

Common causes: missing End Event, unconnected sequence flows, missing task type on Service Tasks (add zeebe:taskDefinition type="...").

429 Too Many Requests — rate limit exceeded

Check the X-RateLimit-Reset header for when the window resets (Unix timestamp). Implement exponential backoff in your worker. Default limit: 300 requests/minute per IP.

Instance stuck at a Service Task indefinitely

The instance is waiting for a worker to pick up the job. Check:

1. Your worker is running and polling the correct type — must match the zeebe:taskDefinition type in your BPMN.
2. The worker is using the correct API key.
3. Poll GET /api/v1/jobs/activate with the correct type and check the response — if it returns an empty jobs array, the type doesn't match.

If the job is returned, your worker logic is the issue. If it returns {"jobs":[]}, check the task type name matches exactly (case-sensitive).

Instance stuck at a User Task

User tasks require a human to claim and complete them. Use the Tasklist UI at /tasklist or call:

DMN evaluation returns null / no matching row

With FIRST hit policy, if no row matches the inputs, the decision returns null. Check:

• Input column values are the correct type (number vs string — 600 ≠ "600")
• Range syntax uses .. not - — use [600..750]
• Add a catch-all row (empty input cells) at the bottom as a default

Webhook not delivered / delivery showing 0 attempts

Check:

1. Webhook is registered and enabled — GET /api/webhooks
2. Your endpoint is publicly reachable (localhost URLs will fail in production)
3. Your endpoint returns HTTP 2xx — any other status triggers a retry
4. Check delivery logs at GET /api/webhooks/logs

Use POST /api/webhooks/test to fire a synthetic payload to all registered endpoints.

Insufficient credits error when starting an instance

Top up via the Wallet page. If you believe your balance is incorrect, check GET /api/usage for the full ledger and contact support@priostack.com with your X-Request-ID.