Integration and implementation support

Common issues

Authentication errors (401)

If you're receiving 401 Unauthorized responses, check the following:

• Your API key is passed in the Authorization header as a Bearer token: Authorization: Bearer vtx_live_...
• The key has not been revoked — check Settings → API Keys in the dashboard.
• You're using a vtx_live_* key against the live API, or a vtx_test_* key against the sandbox.

Scope errors (403)

A 403 Forbidden means your key doesn't have the required scope for the operation. Review the scopes assigned to your key and add the missing ones — see the Authentication guide for a full scope list.

Rate limiting (429)

If you hit rate limits, implement exponential backoff using the Retry-After header returned with 429 responses. For higher limits, consider upgrading your plan or contacting us about Enterprise options.

async function fetchWithRetry(url, options, retries = 3) {
  const res = await fetch(url, options);
  if (res.status === 429 && retries > 0) {
    const retryAfter = parseInt(res.headers.get('Retry-After') || '1', 10);
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    return fetchWithRetry(url, options, retries - 1);
  }
  return res;
}

Webhook delivery failures

If webhooks aren't arriving:

• Confirm your endpoint returns 200 within 10 seconds — slow responses are treated as failures.
• Check that your endpoint is publicly reachable (not localhost).
• Review delivery logs under Settings → Webhooks in the dashboard.
• Verify your signature check isn't rejecting valid payloads — see the Guides page for the correct verification pattern.

Debugging requests

Add the Ventryx-Request-Id header from any response when contacting support — it uniquely identifies the request in our systems and speeds up diagnosis significantly.

curl -i https://api.ventryx.io/v1/workflows \
  -H "Authorization: Bearer $VENTRYX_API_KEY" \
  | grep -i 'ventryx-request-id'

Contact technical support

If you can't resolve the issue using the resources above, reach out directly. Include:

• The Ventryx-Request-Id from the failing request
• The full error response body
• The endpoint and HTTP method
• Your organization slug (visible in dashboard settings)

Contact Support

Useful resources

• Getting Started guide
• API Reference
• Authentication & scopes
• Code examples