Troubleshooting

9 min

Troubleshooting

This section covers the most common issues encountered when building and testing an ACI integration, along with their likely causes and resolutions.

Verify Fails or Returns an Error

Symptom: The Verify test in Sine's integration settings fails, returns a non-SUCCESS response, or times out.

Likely cause	Resolution
Endpoint is not publicly accessible	Confirm the URL is reachable from the internet. If testing locally, ensure your tunnelling tool (e.g. ngrok) is running and the URL is current.
Wrong URL registered in Sine	Check the endpoint URL configured by your Sine contact matches the path your server is listening on.
SSL certificate issue	Ensure your endpoint uses HTTPS with a valid, CA-signed certificate. Self-signed certificates will be rejected in production.
API key mismatch	Confirm the key configured in Sine matches the key your endpoint validates against. Check for leading/trailing whitespace.
Endpoint returning unexpected format	Verify returns { "code": "SUCCESS" } - any other response body or non-200 status is treated as a failure.

Provision Fails - Visitor Cannot Check In

Symptom: Check-in fails or stalls; the visitor is not issued a credential.

Provision is blocking - any failure here prevents check-in from completing.

Likely cause	Resolution
Endpoint timeout	Sine has a timeout on Provision. If your ACS call is slow, consider async credential creation with a fast synchronous response where possible. Keep Provision response time under 5 seconds.
Returning 200 instead of 201	Provision expects HTTP 201 Created. Check your framework's default status code for POST responses.
Missing data.barcode or data.accessControlVisitId in response	Both fields are required. Sine cannot complete credential issuance without them.
barcode is empty or null	Ensure your ACS credential generation returns a non-empty value before you respond.
ACS connectivity failure	Your integration cannot reach the ACS. Check network connectivity, ACS availability, and credentials used to call the ACS API. Return 5xx so Sine can distinguish this from a request error.
Duplicate visitId causes ACS conflict	If Sine retries Provision, your endpoint must handle a repeat visitId idempotently. Return the existing barcode and accessControlVisitId rather than failing.

Activate Fails - Visitor Checked In But Cannot Access

Symptom: Check-in completes in Sine but the credential does not work at readers.

Activate is non-blocking - Sine considers the visitor checked in regardless. Failures here are logged but do not surface to the visitor in Sine.

Likely cause	Resolution
accessControlVisitId not found	Your endpoint could not resolve the ACS holder. Ensure you are persisting the accessControlVisitId returned from Provision and matching it on Activate.
badgeNumber mismatch	The badgeNumber in Activate must match the barcode returned in Provision. If they differ, your Provision response may have returned an unexpected value.
Credential still in inactive state	Your ACS enable/activate call may have failed silently. Add logging around the ACS API call and check for errors.
ACS connectivity failure at Activate time	Your endpoint received the request but could not reach the ACS. Return 5xx - Sine may retry.
Idempotency issue	A second Activate call for the same visit returned an error instead of ACTIVATED. Implement idempotent handling.

Deprovision Fails - Credential Not Revoked

Symptom: Visitor is checked out in Sine but credential still works at readers.

Deprovision is non-blocking - Sine checks the visitor out regardless. Persistent failures should be investigated as they may leave credentials active.

Likely cause	Resolution
accessControlVisitId not found	ACS record may have already been deleted. Return DEPROVISIONED for not-found cases rather than 404 or 500.
deactivateOnly=true not handled	If your integration receives ?deactivateOnly=true but performs a full delete, or vice versa, access state may be inconsistent. Verify your query parameter parsing.
ACS connectivity failure	Log the failure and consider a retry queue for critical deprovision operations in your implementation.

ACS-Initiated Checkout Not Working

Symptom: Visitor badges out at an exit reader but Sine does not check them out.

Likely cause	Resolution
ACS not calling checkoutUrl	Confirm your ACS exit reader is configured to call the URL provided in the Provision request body.
x-sine-api-key header missing	Sine rejects callbacks without this header. Confirm your ACS sends x-sine-api-key with the correct value.
Calling the wrong URL format	The checkoutUrl is a complete, pre-formed URL (JWT embedded in path, teamId as query param). Use it exactly as provided - do not modify or reconstruct it.
checkoutUrl not included in Provision request	This URL is only included when Deprovision on check-out is enabled in the Sine integration settings. Confirm this setting is active for the relevant visitor type.

Access Groups Not Appearing in Sine

Symptom: Administrators cannot select access groups when configuring the integration in Sine.

Likely cause	Resolution
Access Groups endpoint not registered	This is an optional endpoint. Confirm it has been provided to your Sine contact and is configured in the integration settings.
Endpoint returning unexpected shape	Response must include a results array. Each item must have id and name. Any other shape is ignored.
Endpoint returns an error	Check your Access Groups endpoint logs. A non-200 response or malformed JSON will prevent groups from loading.
Caching serving stale data	If you recently updated your ACS group configuration, cache may be serving old results. Check your Cache-Control header settings.

Unexpected Field Values or Missing Data

Symptom: Request bodies contain unexpected, missing, or differently-named fields than expected.

Scenario	Notes
credentialType is absent	This field is optional and only present when configured. Do not hard-fail if it is missing - default to your integration's standard credential type.
accessGroups is an empty array or absent	This is normal. Some sites do not configure access groups. Your integration should handle a missing or empty accessGroups gracefully.
host object is absent	Visits without a designated host do not include the host field. Do not treat its absence as an error.
externalId is absent	Only included if configured. Treat as optional throughout.
zoneId / zoneDetails appear in requests	These are legacy fields from an older feature. You may receive them on some older configurations. Ignore them safely if your integration does not use zones.

Getting Help

If you have ruled out the above causes and cannot resolve the issue:

Collect your logs - Include the full request body (excluding the Authorization header value), your endpoint's response, and any downstream ACS error messages.

Note the visitId - This is the primary correlation key Sine uses. Include it in any support request.

Contact your Sine representative - Provide the above information along with a description of the expected versus actual behaviour.