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

# Integration Troubleshooting

> Troubleshoot common integration issues — API errors, webhook failures, n8n problems, and NFS-e issuance.

# Integration Troubleshooting

Common issues when connecting SalesOS with external tools, and how to resolve them.

## API Connection Issues

### 401 Unauthorized

**Symptom**: API returns `401 Unauthorized` for every request.

**Causes and solutions**:

<AccordionGroup>
  <Accordion title="Token expired">
    JWT tokens expire after 24 hours. Request a new token using your client credentials or refresh token. See the [Authentication guide](/api/authentication).
  </Accordion>

  <Accordion title="Token missing or malformed">
    Ensure the Authorization header is formatted as `Bearer YOUR_TOKEN` (with a space after "Bearer"). Do not include quotes around the token.
  </Accordion>

  <Accordion title="Wrong audience">
    When requesting a token, the `audience` parameter must be `https://api.play2sell.com`. An incorrect audience generates a valid token that SalesOS does not accept.
  </Accordion>

  <Accordion title="Revoked API client">
    Your API client may have been deleted or deactivated by an administrator. Check **Admin > Integrations > API Keys** to verify.
  </Accordion>
</AccordionGroup>

### 403 Forbidden

**Symptom**: API returns `403 Forbidden` for specific endpoints.

**Solution**: Your API client does not have the required scope. Edit the API client in **Admin > Integrations > API Keys** and add the necessary scopes (e.g., `leads:write`, `deals:read`).

### 429 Too Many Requests

**Symptom**: API returns `429` after many rapid requests.

**Solution**: You have exceeded your rate limit. Implement these strategies:

1. Check the `Retry-After` header for when you can resume
2. Add delays between requests (especially in loops)
3. Use pagination efficiently — fetch larger pages to reduce total requests
4. Cache responses where possible
5. Consider upgrading your plan for higher limits

## Webhook Issues

### Webhooks Not Firing

If you are not receiving webhook events:

<Steps>
  <Step title="Check webhook status">
    Go to **Admin > Integrations > Webhooks**. Verify the webhook is set to **Active**.
  </Step>

  <Step title="Verify the URL">
    Ensure the webhook URL is correct and uses HTTPS. HTTP URLs are rejected.
  </Step>

  <Step title="Check event subscriptions">
    Confirm you are subscribed to the correct event types. A webhook set to `deal.won` will not fire for `deal.created`.
  </Step>

  <Step title="Check the delivery log">
    Open the webhook details and review the delivery log. Failed deliveries show the HTTP status code and error message from your server.
  </Step>

  <Step title="Test your endpoint">
    Use `curl` to send a test POST request to your webhook URL and verify it returns `200`.
  </Step>
</Steps>

### Webhook Receiving Duplicate Events

**Cause**: Retries due to slow or failed responses from your server.

**Solution**:

* Ensure your server responds with `200` within 10 seconds
* Use the event `id` field for deduplication
* Process payloads asynchronously — respond immediately, handle the data in a background job

### Webhook Auto-Deactivated

**Cause**: 10 consecutive delivery failures automatically deactivate the webhook.

**Solution**:

1. Fix the underlying issue with your endpoint
2. Go to **Admin > Integrations > Webhooks**
3. Reactivate the webhook
4. Test with a manual event to confirm it works

## SalesOS Connect (n8n) Issues

### Workflow Not Triggering

* Verify the workflow is set to **Active** (toggle is on)
* Check that the trigger node is correctly configured
* For webhook triggers, ensure the webhook URL in SalesOS matches the n8n webhook node URL
* Check n8n execution log for errors

### Workflow Fails Mid-Execution

* Open the failed execution in the n8n execution log
* Click the failed node to see the error details
* Common issues:
  * **Authentication expired** — Update credentials in the n8n node
  * **Invalid data format** — Add a transformation node to fix data mapping
  * **External service unavailable** — Add error handling with a retry mechanism

### n8n Credential Errors

If n8n cannot authenticate with SalesOS:

1. Go to the n8n credential settings
2. Update the SalesOS API token
3. Test the connection
4. Re-run the failed workflow

<Tip>
  Set up error notifications in n8n workflows. Add an error trigger node that sends you an email or Slack message when any workflow fails.
</Tip>

## NFS-e Issues

### Client Registration Fails

* Verify the CNPJ/CPF is valid (correct number of digits, valid check digits)
* Ensure all required fields are filled: name, CNPJ/CPF, address
* Check if the client already exists (duplicate CNPJ)

### NFS-e Issuance Fails

Common errors:

| Error                     | Solution                                                      |
| ------------------------- | ------------------------------------------------------------- |
| Invalid service code      | Select a valid municipal service code                         |
| Client not found          | Register the client first                                     |
| Tax authority unavailable | Wait and retry — municipal systems have scheduled maintenance |
| Invalid tax configuration | Review your tax regime settings with your accountant          |

<Warning>
  NFS-e errors sometimes carry Portuguese messages from the municipal tax authority. If you cannot interpret the error, contact SalesOS support together with your accountant.
</Warning>

## General Troubleshooting Steps

If none of the specific solutions above help:

1. **Check the SalesOS status page** for any ongoing incidents
2. **Review recent changes** — Did someone modify API keys, webhook URLs, or integration settings?
3. **Test with minimal configuration** — Create a simple test (e.g., a single API call) to isolate the issue
4. **Check logs** — Review webhook delivery logs, n8n execution logs, and your server logs
5. **Contact support** — Include error messages, request IDs, and reproduction steps

<CardGroup cols={2}>
  <Card title="API Overview" icon="code" href="/api/overview">
    Review API documentation
  </Card>

  <Card title="Contact Support" icon="headset" href="/support/contact">
    Get help from our team
  </Card>
</CardGroup>