Skip to main content

​
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:
JWT tokens expire after 24 hours. Request a new token using your client credentials or refresh token. See the Authentication guide.
Ensure the Authorization header is formatted as Bearer YOUR_TOKEN (with a space after “Bearer”). Do not include quotes around the token.
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.
Your API client may have been deleted or deactivated by an administrator. Check Admin > Integrations > API Keys to verify.

​
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:
1

Check webhook status

Go to Admin > Integrations > Webhooks. Verify the webhook is set to Active.
2

Verify the URL

Ensure the webhook URL is correct and uses HTTPS. HTTP URLs are rejected.
3

Check event subscriptions

Confirm you are subscribed to the correct event types. A webhook set to deal.won will not fire for deal.created.
4

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.
5

Test your endpoint

Use curl to send a test POST request to your webhook URL and verify it returns 200.

​
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
Set up error notifications in n8n workflows. Add an error trigger node that sends you an email or Slack message when any workflow fails.

​
Omie ERP Issues

​
Connection Test Fails

  • Verify your Omie App Key and App Secret are correct
  • Ensure your Omie account is active and has API access enabled
  • Check if Omie is experiencing downtime (check their status page)

​
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 in Omie (duplicate CNPJ)

​
NFS-e Issuance Fails

Common errors:
ErrorSolution
Invalid service codeSelect a valid service code from your Omie configuration
Client not foundRegister the client in Omie first using pay-cadastrar-cliente
Tax authority unavailableWait and retry — municipal systems have scheduled maintenance
Invalid tax configurationReview your tax regime settings in Omie with your accountant
Omie API errors sometimes return Portuguese error messages from the municipal tax authority. If you cannot interpret the error, contact both Omie support and your accountant.

​
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

API Overview

Review API documentation

Contact Support

Get help from our team