Skip to main content

Analyst Troubleshooting

Common issues analysts encounter and how to resolve them.

Pagination Issues​

Pagination Not Working​

Symptoms: Only first page of data collected

Check:

  1. Is pagination enabled for the endpoint?
  2. Is the cursor param name correct?
  3. Is the next cursor path correct?
  4. Is the stop condition configured?

Debug:

  1. Test endpoint manually
  2. Check response for cursor field
  3. Verify JSON path matches response structure
  4. Check API logs for pagination requests

Pagination Never Stops​

Symptoms: Collection runs indefinitely

Check:

  1. Stop condition is configured
  2. Cursor path returns different values
  3. Stop condition logic is correct

Debug:

  1. Check API logs for repeated requests
  2. Verify cursor value changes between requests
  3. Add or fix stop condition

Dependency Issues​

No Values Extracted​

Symptoms: Dependent endpoints don't receive values

Check:

  1. JSON path is correct
  2. Source endpoint returned data
  3. Array notation is correct ([*] for arrays)

Debug:

  1. Test source endpoint individually
  2. Verify JSON path in response
  3. Check for typos

Dependencies Fail​

Symptoms: Dependent endpoints return errors

Check:

  1. Parameter location (path vs query)
  2. Parameter name matches endpoint spec
  3. Extracted values are valid for target

Debug:

  1. Review API logs for request details
  2. Compare with working API calls
  3. Test with single value manually

Authentication Issues​

401 Unauthorized​

Causes:

  • Invalid credentials
  • Expired token
  • Wrong credential type

Solutions:

  1. Verify credential is still valid
  2. Check expiration date
  3. Request new credentials from customer

403 Forbidden​

Causes:

  • Missing permissions/scopes
  • Resource access denied
  • IP restrictions

Solutions:

  1. Review required scopes for endpoint
  2. Request additional permissions
  3. Check platform's access restrictions

Connector Issues​

Generation Fails​

Symptoms: Automated generation errors

Causes:

  • URL not accessible
  • Unsupported format
  • Invalid specification

Solutions:

  1. Verify URL is publicly accessible
  2. Try different documentation URL
  3. Use manual creation if needed

Endpoints Missing​

Symptoms: Expected endpoints not in connector

Causes:

  • Not in documentation
  • Parsing error
  • Hidden/internal endpoints

Solutions:

  1. Add missing endpoints manually
  2. Try different documentation source
  3. Contact platform for full API docs

Collection Issues​

Collection Stuck​

Symptoms: Status doesn't change

Check:

  1. Worker is running
  2. Redis connection active
  3. No queue errors

Debug:

  1. Check worker logs
  2. Verify Redis connectivity
  3. Check for job errors

Partial Collection​

Symptoms: Some endpoints failed

Review:

  1. Which endpoints failed
  2. Error codes and messages
  3. Pattern to failures

Actions:

  1. Fix connector if config issue
  2. Request new credentials if auth issue
  3. Document and sign off with notes if acceptable

Rate Limiting​

429 Too Many Requests​

Causes:

  • Connector rate limit too high
  • Page size too large
  • Multiple collections simultaneously

Solutions:

  1. Reduce connector rate limit
  2. Decrease page size
  3. Queue collections instead of parallel
  4. Contact platform for rate increase

Data Issues​

Missing Data​

Symptoms: Less data than expected

Check:

  1. All relevant endpoints enabled?
  2. Pagination collecting all pages?
  3. Dependencies mapping correctly?
  4. Scope configuration too narrow?

Debug:

  1. Review endpoint list
  2. Check pagination logs
  3. Verify dependency chain
  4. Adjust date range or filters

Hash Validation Failures​

Symptoms: Files show validation failed

Causes:

  • File corrupted during transfer
  • Hash computed before upload complete
  • Bug in collection process

Actions:

  1. Do NOT sign off
  2. Report to engineering
  3. May need to re-run collection

Best Practices for Troubleshooting​

  1. Check logs first - Most issues visible in API logs
  2. Test in isolation - Test single endpoints before chains
  3. Compare working/broken - What's different?
  4. Document findings - Help future troubleshooting
  5. Escalate when needed - Some issues need engineering

Getting Help​

If these solutions don't resolve your issue:

  1. Review API logs - Detailed request/response information
  2. Search existing issues - May be known problem
  3. Document thoroughly - Capture error details
  4. Contact engineering - For complex technical issues

When escalating, include:

  • Connector name and version
  • Collection ID (if applicable)
  • Error messages
  • Steps to reproduce
  • What you've already tried