Troubleshooting
Troubleshooting
When testing the proposed integration, compare Sine activity with your service's redacted request and response diagnostics and the cabinet's state. A successful Sine check-in is not, by itself, proof that cabinet access was created or activated.
Sine Cannot Reach an Endpoint
Possible cause | What to check |
|---|---|
Incorrect endpoint URL | Confirm that each configured URL points to the intended operation |
Your service is unavailable | Check service health, routing and upstream availability |
TLS certificate is invalid or expired | Install a valid certificate for the endpoint hostname |
A firewall or network policy blocks the request | Allow the approved Sine-to-service connection path |
The request times out | Check service and cabinet latency; the generic timeout policy is still to be confirmed |
Generic KMI is not available in the environment | Confirm availability and the final setup requirements with Sine |
Use HTTPS and do not disable certificate validation to work around connection problems.
Endpoint Rejects Authentication
Possible cause | What to check |
|---|---|
KMI API keys do not match | Update the secret in the authorised systems without exposing its value |
The service expects a different header format | The proposal sends the configured API key as the Authorization value without adding a prefix |
The key is valid but not authorised for the customer | Check the association between the key and config.externalId |
Cabinet API credentials are invalid | Check the separate credentials your service uses for the cabinet |
Do not confuse the KMI API key with a visitor's cabinet PIN or with the cabinet API credentials. Never include these values in support tickets.
Key Groups or Keys Are Missing
Possible cause | What to check |
|---|---|
Wrong externalId | Confirm that it selects the intended customer and cabinet configuration |
Resources response has the wrong shape | Return a top-level keyGroups array with stable string IDs and names |
Wrong selected groups | Check the group IDs passed to Keys and their membership in the cabinet |
Cabinet API results are paginated | Retrieve every required page before returning a successful inventory |
Duplicate keys occur across groups | Deduplicate keys by their stable cabinet ID |
A key ID is too long for the Sine asset identifier | Check the site's asset-type prefix and the proposed identifier-length constraint; do not truncate IDs blindly |
Keys response has the wrong shape | Return SUCCESS and a complete data array of key IDs and names |
A successful Keys response is treated as the proposed inventory snapshot. Missing entries may be removed from Sine. If your service cannot retrieve the complete inventory, return an error rather than an empty or partial success.
Visitor Checks In but No Cabinet User Is Created
Possible cause | What to check |
|---|---|
Visitor did not select a key | Confirm the check-in form uses the synchronised key list and the visitor selected an option |
No visitor email or mobile was supplied | Provide a supported contact detail; email is needed for credential email |
Provision request is invalid | Check externalId, visitId, visitor fields, validity and the requested key IDs |
Cabinet user creation failed | Inspect your service's redacted result and cabinet permissions |
Provision response is incomplete | Return PROVISIONED with non-empty data.keyUserId and data.password |
A request timed out after creation | Reconcile the visit against cabinet records before creating another user |
The proposed lifecycle records a handled provisioning failure without rejecting check-in solely because the cabinet call failed. Provision is awaited, so a slow service can still delay pass creation.
Cabinet User Cannot Collect Keys
Possible cause | What to check |
|---|---|
Pass is pending approval | Wait for the applicable approval; Activate is proposed to occur after acceptance |
Activate failed | Check the request, service response and cabinet permission update |
Wrong key IDs were mapped | Use the IDs your service returned from Keys, not Sine asset IDs, and map them to cabinet IDs if needed |
Cabinet validity or permissions are wrong | Check the visitor's time window, key permissions and cabinet policy |
Visitor is using the wrong credentials | Use the visitor's cabinet user ID and PIN, not the KMI API key |
Provision and Activate are separate operations. Do not grant the requested key permissions to every provisioned user before activation.
Visitor Does Not Receive Credentials
Possible cause | What to check |
|---|---|
No visitor email was supplied | Collect an email address when the visitor needs emailed credentials |
Activate did not succeed | Resolve the activation failure before investigating credential delivery |
Provision returned missing credentials | Return non-empty keyUserId and password values |
Email delivery failed | Check the available Sine notification diagnostics |
The proposed lifecycle attempts email after successful activation; mobile contact alone does not imply SMS credential delivery. Do not copy a visitor PIN into logs while investigating.
Key Return Status Is Wrong or Uncertain
Compare the requested key IDs and cabinet user ID with the cabinet's custody records and your service's classification rules.
- Return outstanding requested key IDs in the top-level unreturnedKeyIds array, using the same IDs supplied in the request.
- Preserve key IDs exactly, including leading zeroes.
- Check how your service handles missing records, incomplete custody data and keys held by another user.
- Return an error if your service cannot establish a trustworthy result; do not silently treat an unknown state as a confirmed return.
- Involve the site operator when physical cabinet inspection is required.
An empty unreturnedKeyIds array means that no requested keys are classified as outstanding under the proposed contract. Check-return does not itself update Sine asset assignments.
Cabinet Access Ends While Keys Are Outstanding
The proposed lifecycle schedules deprovision after a 15-minute grace delay and attempts it even if keys remain outstanding or a return check fails. The delay and generic-framework behaviour still require confirmation.
Arrange physical-key recovery with the site operator. Do not assume that access is extended automatically or that a second reminder is sent.
Cabinet Access Remains After Check-Out
Possible cause | What to check |
|---|---|
The grace delay has not elapsed | Allow for the proposed delay and subsequent task execution |
Deprovision was not received | Check your endpoint diagnostics and the available Sine activity |
Deprovision failed | Check cabinet connectivity, user mapping and permissions |
Your service removed the wrong permission | Review the externalId, keyUserId and requested-key mapping |
A prior Provision did not succeed | Check whether a valid cabinet user ID was returned and recorded |
Escalate access that remains active unexpectedly. The generic retry and delivery guarantees are not yet defined.
Duplicate Cabinet Users Appear
A repeated Provision request or a timeout after the cabinet accepted a write can leave the outcome uncertain.
For Provision, correlate the customer and visitId with cabinet records before retrying. Retain the mapping to keyUserId: later operations send that user ID, not visitId. Implement a documented recovery process and make repeated requests safe where the cabinet supports it. Do not assume a timed-out request had no effect or that requests are delivered exactly once.
Getting Help
Provide your integration support team or Sine contact with:
- The customer externalId, Sine site and affected pass ID.
- The operation, time and timezone.
- A request correlation identifier, if one is available.
- The HTTP status and a redacted error message.
- The expected and observed cabinet state.
- Whether the issue occurred during inventory, provisioning, activation, return checking or deprovisioning.
Exclude API keys, cabinet passwords, visitor PINs and unredacted personal data.