--- title: Troubleshooting slug: frameworks/xnu8-aci-reference-and-troubleshooting createdAt: 2026-05-26T06:23:39.000Z --- # 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: 1. **Collect your logs** - Include the full request body (excluding the `Authorization` header value), your endpoint's response, and any downstream ACS error messages. 2. **Note the **`visitId` - This is the primary correlation key Sine uses. Include it in any support request. 3. **Contact your Sine representative** - Provide the above information along with a description of the expected versus actual behaviour.