SalesLoft Common Errors Skill

SalesLoft Common Errors

Overview

Quick reference for the most common SalesLoft REST API v2 errors. All errors return JSON with a message field. Rate limiting uses a cost-based system (600 cost/minute).

Error Reference

401 Unauthorized -- Invalid or Expired Token

{ "error": "Not authorized", "error_description": "The access token is invalid" }

Causes: Token expired, revoked, or wrong environment key.

Fix:

// Check if token works
const { data } = await api.get('/me.json').catch(err => {
  if (err.response?.status === 401) {
    console.error('Token invalid. Refreshing...');
    return refreshAccessToken(storedRefreshToken);
  }
  throw err;
});

403 Forbidden -- Insufficient Scopes

{ "error": "Forbidden", "error_description": "Insufficient scope for this resource" }

Fix: Check app scopes in developer portal. Common issue: using user-level OAuth for team-level endpoints (cadences, team templates).

404 Not Found -- Wrong Endpoint or Deleted Resource

# Verify endpoint format -- all endpoints end with .json
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.salesloft.com/v2/people/12345.json
# NOT /people/12345 (missing .json suffix)

422 Unprocessable Entity -- Validation Errors

{
  "errors": [
    { "attribute": "email_address", "message": "is required" },
    { "attribute": "email_address", "message": "has already been taken" }
  ]
}

Common 422 causes: | Field | Error | Solution | |-------|-------|----------| | email_address | required | Must include when creating a person | | email_address | already taken | Use GET /people.json?email_addresses[]=x first | | cadence_id | not active | Cadence must have current_state: 'active' | | person_id | already enrolled | Check existing cadence memberships |

429 Too Many Requests -- Rate Limit Exceeded

X-RateLimit-Limit-Per-Minute: 600
X-RateLimit-Remaining-Per-Minute: 0
Retry-After: 42

SalesLoft uses cost-based rate limiting:

Default: each request costs 1 point
Pages 101-150: 3 points per request
Pages 151-250: 8 points per request
Pages 251-500: 10 points per request
Pages 501+: 30 points per request

// Auto-retry with Retry-After header
api.interceptors.response.use(undefined, async (error) => {
  if (error.response?.status === 429) {
    const wait = parseInt(error.response.headers['retry-after'] || '60');
    await new Promise(r => setTimeout(r, wait * 1000));
    return api.request(error.config);
  }
  throw error;
});

5xx Server Errors

Fix: Retry with exponential backoff. Check status.salesloft.com for outages.

Quick Diagnostic

# 1. Verify token
curl -s -H "Authorization: Bearer $SALESLOFT_API_KEY" \
  https://api.salesloft.com/v2/me.json | jq '.data.email'

# 2. Check API status
curl -s https://status.salesloft.com/api/v2/status.json | jq '.status'

# 3. Test specific endpoint
curl -v -H "Authorization: Bearer $SALESLOFT_API_KEY" \
  'https://api.salesloft.com/v2/people.json?per_page=1'

# 4. Check rate limit remaining
curl -sI -H "Authorization: Bearer $SALESLOFT_API_KEY" \
  https://api.salesloft.com/v2/people.json | grep -i ratelimit

Error Handling

| Status | Retryable | Action | |--------|-----------|--------| | 401 | No | Refresh token or re-authenticate | | 403 | No | Update app scopes in developer portal | | 404 | No | Check endpoint URL (must end in .json) | | 422 | No | Fix request payload | | 429 | Yes | Wait for Retry-After header value | | 500-503 | Yes | Exponential backoff, check status page |

Resources

Next Steps

For comprehensive debugging, see salesloft-debug-bundle.

Agent Skills: SalesLoft Common Errors

Install this agent skill to your local

Skill Files