Troubleshooting

Start with the environment, operation, stable error code, and authorization trace ID. A decision such as hold selects the review path. Keep its request pending while you inspect the reason and complete the next step.

Canonical API errors use problem documents with a machine-readable code. The Node client exposes GrayPassApiError.status and .code; match these rather than human-readable detail text. Full request and response contracts are in the API reference.

Credentials and isolation

Symptom	Likely cause	Next step
Unauthorized request	Missing, expired, revoked, or inappropriate credential	Check the active credential and its scope without logging the secret
`error.not_found` for a known identifier	Wrong tenant or resource boundary	Confirm the authenticated tenant and identifier source
`error.environment_mismatch`	Sandbox and live values mixed	Match the credential, subject, action, and requested environment
`error.browser_credential_not_allowed`	Browser token used on a server operation	Move authorization or subject administration to the backend
`error.caller_not_allowed`	Credential not permitted by the active policy or request chain	Review allowed callers and use the expected authenticated backend
Origin rejected	Scheme, host, or port differs from registration	Register the intended exact origin and mint its token

Cross-tenant resources can appear absent. Retrieve the identifier from your own authenticated application mapping and verify the credential identity before retrying.

Enrollment and evidence

If readiness never becomes true, inspect accepted window count, active seconds, modalities, and rejection reasons. Elapsed wall-clock time is not coverage. evidence.rejected_unsigned indicates missing or invalid signing; evidence.rejected_replay indicates repeated or overlapping counted input; evidence.rejected_quality indicates integrity or quality rejection.

When the SDK reports paused transport, inspect connectivity, registered origin, token expiry, page lifecycle, and whether the session ended. Use the supported refresh-token callback if your application mints replacement tokens. Do not keep submitting evidence after revocation or teardown.

error.subject_not_enrolled requires completed server-side enrollment, not a browser flag. error.subject_not_found may indicate an incorrect environment. Re-enrollment and recovery should follow the declared subject policy.

Actions, policies, and request binding

Code	Meaning and response
`error.action_not_registered` or `error.action_archived`	Check the exact action key and environment; register or select an active action
`error.policy_inactive`	Create and activate an intact policy version
`error.policy_conflict`	A concurrent change raced with the request; re-read before retrying
`error.policy_integrity`	Stored policy no longer matches its digest; keep the gate closed and report the trace
`error.context_invalid`	Validate the supported schema subset and request field values
`error.audience_not_allowed`	Use a relying-party audience allowed by the active policy
`error.enforcement_not_approved`	The requested enforcement configuration was rejected; preserve the existing mode and contact support with the environment and trace ID
`error.request_stale`	Correct server clock or create a fresh request
`error.nonce_reused`	A nonce was reused outside its allowed idempotent request
`error.idempotency_conflict`	The same key was used for different request material
`error.request_in_progress`	Wait and retry the same request
`error.idempotency_stale`	Subject, action, or policy state changed; request fresh authorization

Do not fix request-binding errors by omitting the destination or dropping verifier checks. Preserve the full approved operation.

Repeated challenges or holds

Inspect coverage, freshness, session association, and typed claim requirements. decision.insufficient_evidence can correctly map to challenge or hold. Confirm an observation session for the same subject is active and use the actual accepted evidence status.

An operator_change.detected or automation.detected hold survives a challenge when the policy requires review. Scripted input may trigger automation signals. Keep the operation pending for an attributed review, or stop it. If the result is unexpected, retain the authorization ID and the accepted-evidence status for investigation.

An expired challenge requires a new authorization. error.challenge_mismatch can indicate a wrong request, duplicate completion, or disallowed method. sandbox_confirm is permitted only in sandbox and is not a passkey ceremony.

Proof failures

For issuer_mismatch, check the explicitly configured expected issuer. For unknown_kid, refresh JWKS from the configured GrayPass origin. For audience, tenant, environment, or action-hash mismatch, compare against your trusted pending request and credential identity. Never fix a mismatch by copying the proof's own claim into the expected value.

For expired, obtain fresh authorization. For not_enforceable, inspect mode and actor. For replay, revocation, or consumption failure, refuse execution and reconcile your request ledger. A successful offline signature check cannot override online refusal.

error.proof_unavailable means an enforceable proof could not be issued. Keep the operation unexecuted. A dependency timeout may be ambiguous; do not assume a business mutation or proof consumption failed without checking durable state.

Optional camera

If permission is refused, preserve the non-camera path. If models fail to load, inspect first-party assetBase, complete worker/model/WASM files, MIME types, page worker permission, and the worker response's WASM policy. If calibration does not become ready, use local guidance and let the person retry or stop. A hidden page stops the camera and a restart requires fresh calibration. See Optional camera.

Webhooks and billing

For signature failures, retain exact raw bytes, require all V2 headers, confirm the correct signing secret, and check clock skew. Use the logical canonical metadata.event_id for deduplication. Inspect dead letters and reconcile authoritative state; missing notifications do not imply missing activity.

For billing differences, compare meter definitions, qualifying production activity, contractual window boundaries, allowances, corrections, and credits. Commercial access errors are not authorization allows. See Invoices and payments.

Send a useful support report

Send the environment, timestamp and timezone, code, safe trace identifier, SDK and policy versions, reproduction steps, and expected versus observed behavior to founders@graypass.org. Redact secrets, raw proofs, payment details, and personal data. Your application's request ledger can establish whether the business operation ran; do not infer execution only from a GrayPass decision.