Troubleshooting

Find the fastest path through authentication, quota, callback, Watch, and deployment problems.

When something does not look right, start with the API response rather than a notification or cached browser view. ActionBox returns a stable error code, a human-readable message, and an X-Request-ID response header that support can use to find the request.

First checks

Confirm the request is going to https://api.actionbox.cloud, not a dashboard URL or an old local port.
Check that the credential belongs to the operation: Source keys (axb_live_... or axb_test_...) are for machine calls; user sessions are for dashboard and user-scoped calls.
Save the HTTP status, JSON error code, and X-Request-ID. Do not save the raw token, webhook secret, or Watch URL.
Retry only when the error is transient. Preserve the same Idempotency-Key when retrying a create request.

curl -fsS https://api.actionbox.cloud/health
curl -fsS https://api.actionbox.cloud/ready

/health checks process liveness. /ready checks whether the public API's required services are ready. Neither endpoint proves that an authenticated Action, callback, notification, or Watch is healthy.

A timeout is not a decision

A local CLI or SDK wait can time out while the server-side Action remains open. Re-read the Action or use its callback; never convert a client timeout into an automatic rejection unless your own workflow explicitly defines that policy.

Symptoms, causes, and fixes

Symptom	Likely cause	What to do
`401 AUTH_REQUIRED` or `INVALID_API_KEY`	Missing, expired, malformed, or wrong credential class	Sign in again for a user session. For machine calls, load the Source key from a secret manager and check that it has not been revoked.
`401 SOURCE_REVOKED`	The Source or its key was revoked	Create or rotate a Source key, update the worker secret, and retry with a new credential. Existing Action history is retained.
`403 WORKSPACE_ROLE_REQUIRED`	The signed-in member cannot manage that resource	Ask an owner or admin to perform Source/Watch management, assignment, or webhook retry. Approvers can review and decide Actions; viewers are read-only.
`403 SOURCE_LIMIT_REACHED`, `DEVICE_LIMIT_REACHED`, or `WATCH_LIMIT_REACHED`	The workspace has reached a plan capacity limit	Revoke/archive an unused resource or review the plan on the billing page. Do not create duplicate resources while retrying.
`404 ACTION_NOT_FOUND` or `WATCH_NOT_FOUND`	Wrong workspace/Source, archived resource, revoked credential, or unavailable resource	Re-read the resource using the owning credential. If Watch routes remain unavailable, check ActionBox service status and contact support.
`409 ACTION_NOT_OPEN` or `ACTION_CHANGED`	Another actor already resolved/updated the Action, or the review snapshot is stale	Fetch the current Action and branch on its terminal state. When resolving a reviewed snapshot, send the current `action_version` and `fingerprint`.
`409 IDEMPOTENCY_KEY_REUSED`	The same idempotency key was sent with a different request body	Use a new key for a genuinely new request. Keep the old key for exact retries.
`409 OUTCOME_ALREADY_REPORTED`	An execution outcome already exists	Treat an exact retry as success; do not try to rewrite an immutable outcome.
`413 PAYLOAD_CONTEXT_TOO_LARGE`	The Action context is larger than the plan allows	Reduce or summarize context. Keep secrets, transcripts, and large artifacts out of the Action; link to an access-controlled system instead.
`429 RATE_LIMITED`	A Source, user, IP, or plan hourly limit was reached	Honor `Retry-After`, use bounded backoff, and avoid retrying every worker at once.
`429 QUOTA_EXCEEDED`	The Developer plan reached its monthly live Action allowance	Use a test key for protocol checks, wait for the next period, or review an eligible paid plan. Exact idempotency and dedupe replays remain safe.
Callback is `retrying` or `failed`	Receiver timeout/error, an HTTP 429/5xx, invalid destination, or signature handling failure	Inspect the delivery status and attempt history, then fix the receiver. A callback problem does not undo the Action decision.
Watch is `down`	Missed schedule, explicit `fail`, or runtime exceeded its limit	Check the job clock/timezone, grace window, signal method, and worker logs. Send `success`/`ping` after the job is healthy; the open incident is then system-resolved.

Authentication problems

Dashboard or user API calls

The web dashboard uses the actionbox_session cookie. Native clients use the equivalent axb_usr_... bearer token. Check the session without exposing it in a log:

curl -fsS https://api.actionbox.cloud/v1/auth/session \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

Use POST /v1/auth/logout to revoke the current session. The available sign-in methods are advertised by GET /v1/auth/providers.

Machine calls

Source keys are scoped to one Source and one environment. A live key does not read another Source's Actions, and a test key does not create live Actions. Check the header shape, not the secret itself:

curl -fsS https://api.actionbox.cloud/v1/me/actions?status=open \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

curl -fsS https://api.actionbox.cloud/v1/actions/act_... \
  -H "Authorization: Bearer $ACTIONBOX_SOURCE_KEY"

If a credential may have leaked, rotate it immediately. See Security for the complete rotation checklist.

Action and decision problems

An Action can be open, resolved, cancelled, or expired. Only open Actions transition. A decision against an older material snapshot fails closed with ACTION_CHANGED; this is protection against approving a request that changed after review.

When a decision succeeds, consume the typed response (or the concise decision for a single-choice Action). A resolved Action records authorization, not execution success. After the downstream operation finishes, report one immutable success or failed outcome with the exact version and fingerprint.

Callback problems

Use the user-scoped delivery endpoints to inspect a callback:

curl -fsS https://api.actionbox.cloud/v1/webhooks/summary \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

curl -fsS https://api.actionbox.cloud/v1/webhooks/whd_... \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

Verify the exact raw request body before parsing JSON. A receiver must accept duplicate deliveries safely by deduplicating the stable event id. See Webhooks and callbacks and Webhook operations.

Watch problems

For a Watch that never arms, send its configured signal once. A new Watch does not alert until its first ping, start, or success signal, or until an operator resumes it. For a POST-only Watch, a GET request returns 405 WATCH_POST_REQUIRED and does not record a heartbeat.

For an unexpected incident, compare:

the persisted timezone and five-field cron expression, or the interval in seconds;
grace_seconds and (when configured) max_runtime_seconds;
the job's actual signal (/start, /success, or /fail);
the Watch's last_heartbeat_at, next_expected_at, and incident_kind.

See Watch operations for a runbook and endpoint map.

When to escalate

Include the endpoint, timestamp with timezone, HTTP status, error code, X-Request-ID, and the affected resource ID. Redact credentials, Watch URLs, full callback URLs containing sensitive path/query data, Action descriptions, response values, and customer data. Do not include a raw request body unless it has been reviewed and scrubbed.

Escalate a suspected platform incident when /health fails, /ready remains unavailable, multiple unrelated callbacks remain stuck, or the Watch evaluator reports a stale service. For a single receiver failure, fix the receiver first and use the owner/admin retry action only after confirming the destination is ready.

Troubleshooting

On this page