> ## Documentation Index
> Fetch the complete documentation index at: https://tapace.lk/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose SDK installation, API key, template, wallet delivery and retry problems, and review the version compatibility checks needed before production use.

Use this checklist to test your TapAce Node.js integration in small steps. Record the SDK version and request ID when investigating an API response.

## Installation or import fails

Check Node.js is version 20 or newer and your application supports ES modules. For a JavaScript entry file, use `.mjs` or an appropriate `"type": "module"` package setting.

The package name is `@tapace/node`, and version `0.1.0` is available from the public npm registry. If a lookup returns 404 immediately after a release, npm may still be processing it or updating package metadata. Wait briefly, then retry with `npm view @tapace/node@0.1.0 version --registry=https://registry.npmjs.org/ --prefer-online`. A registry 404 is separate from a TapAce API authentication error. See [installation instructions](https://tapace.lk/docs/sdk/node/overview.md).

CommonJS applications can load the ES module with dynamic `import()` inside an async function. Use the TypeScript `NodeNext` module and resolution settings when checking a Node ESM application.

## Webhook verification fails

Verify the exact raw bytes before JSON middleware changes them. Check the signing secret separately from the API key, use decimal integer timestamp seconds and keep the server clock synchronized. Malformed base64, extra padding, modified bytes and out-of-window timestamps are rejected. The default tolerance is 300 seconds. See [Webhook verification](https://tapace.lk/docs/sdk/node/webhooks.md).

## The constructor rejects my key

The SDK accepts `tapace_test_` and `tapace_live_` prefixes. Check the server environment variable exists. A key with a valid prefix can still be invalid or revoked; use `tapace.me.retrieve()` to verify it.

Do not include API keys or webhook signing secrets in screenshots, logs or support messages.

## Issuance returns 400 or 422

Retrieve the template and inspect `requiredFields` and `requiredActions`. Match the actual per-pass keys, rather than the labels shown on the pass.

A 400 can indicate missing fields, unsupported wallets, archived templates or invalid values. A 422 can indicate signing setup is incomplete. Check [Test and live](https://tapace.lk/docs/environments.md) and the error's `code`, `issues` and `requestId`.

## Wallet links are null

`appleDownloadUrl` or `googleSaveUrl` may be null when that wallet is unavailable, not enabled for the pass, cannot be signed or the pass is voided. Inspect `tapace.passes.retrieve(id)` for wallet readiness, and use the hosted `distributionUrl` when appropriate.

## The API succeeded but the phone has not changed

Issuance requires the holder to add the pass. Updates and notifications involve asynchronous delivery. Retrieve the returned update, notification or deployment and inspect its progress rather than repeatedly creating a new operation.

For a pass update, `update` can be null when only metadata changed or no wallet-visible change occurred. See [Update passes](https://tapace.lk/docs/guides/update-passes.md).

A silent update has no alert banner. For a message, inspect **Message for you** on the pass's details/back. A successful Apple delivery status confirms the push signal was accepted; confirm the changed field or message separately on the device. Check that Automatic Updates is enabled, and try refreshing the pass.

If an older installation remains stale while a newly downloaded pass has the correct values, collect the pass ID, update ID and approximate update time for support. A known recovery issue can affect older Apple installations after service data is reset. Re-adding a pass can refresh its installation state, but is not a permanent fix for that issue. Do not issue duplicate passes or loyalty credits to work around a display problem.

## A webhook arrives more than once

Repeated deliveries are expected, including when you click **Resend** in the dashboard. Verify every delivery, then deduplicate with the event's `id` in persistent storage. The SDK does not store processed event IDs. Installing the same pass again creates a new lifecycle event and must not be discarded simply because its pass ID matches a previous event.

## A retry keeps returning a conflict

Handle `TapAceIdempotencyError.reason`:

* `in_flight`: retry the original request later, with the same key and body.
* `key_reused`: investigate why the same operation key now has different request details.

A general `TapAceConflictError` can also indicate a stale template revision or another conflict. The SDK does not automatically retry every 409 response. Retrieve current state before deciding what to do.

## A template update fails

Always send the current `expectedRevision`; the SDK type requires it. When sending `issuePlatforms`, include both `apple` and `google` booleans. See [Resource methods](https://tapace.lk/docs/sdk/node/resources.md).

## SDK and API compatibility

Use the documented SDK build and check the following behavior when upgrading an integration:

| Area | Check |
| - | - |
| Pass void/delete | void() uses POST /void; DELETE deletes data and has no SDK wrapper. |
| Template archive/delete | archive() uses POST /archive; DELETE deletes the template and its passes and has no SDK wrapper. |
| Event save | Send an event object; use an empty object to clear details. PUT does not provide stored-response replay. |
| Google event sync | Results expose environment, nullable issuerId and updated/failed status values. |
| Template platforms | Supply both apple and google in issuePlatforms, together with expectedRevision. |
| Expiring links | Use the HTTP API reference; no dedicated SDK methods exist. |

## Suggested test order

1. Verify installation/import and check a test key with `me.retrieve()`.
2. List and retrieve a template; inspect required fields.
3. Issue a pass with a stable key; repeat the exact call and compare IDs.
4. Open its hosted delivery page and add the pass on a test phone.
5. Update a per-pass field and inspect its update record.
6. Test stamps or points with a new saved operation ID for each intended change.
7. Test notification scheduling and cancellation with test passes.
8. Verify a signed webhook and reject a changed body.
9. Test deployments, event changes and lifecycle operations after their compatibility checks.

Template and event changes can affect shared resources across environments. Use a dedicated test template, and review its use before changing it.

See [Errors and retries](https://tapace.lk/docs/sdk/node/reliability.md) for recovery patterns.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.