API Reference
Start typing to search…

General Troubleshooting

Common Issues & Solutions

IssuePossible CausesRecommended Actions
JWT Token request failsIncorrect username/passwordVerify your credentials
Audience creation failsMissing or invalid required fieldsDouble-check payload format and required fields
Data upload failsInvalid viantSegmentId or data typeConfirm segment ID and ensure correct data format
Audience expiration failsMismatched segment IDsEnsure segmentId matches between URL and payload
Opt-out request failsInvalid hash or IP formatUse correct formats: SHA-256 hashes and IPv4
Job status retrieval errorsIncorrect job_idConfirm job ID from the opt-out response

Audience Creation: Common Errors

  1. Missing or Invalid Fields

    • If a required field (e.g., dataType) is missing, the API returns a 400 error.

    • Double-check and fix the payload.

  2. Unauthorized (401/403)

    • Ensure the Authorization header is set.

    • If token is expired, refresh it via POST /v1/oauth2/token/refresh.

  3. Response Field Insight

    • If a viantSegmentId is returned, the audience was created.

    • Status "INACTIVE" is expected until sufficient data is added.

Add Audience Data: Common Errors

  1. Invalid or MissingviantSegmentId

    • Must match the one in the URL.

    • Segment must not be archived.

  2. Hash Format Issues

    • For email_sha256, ensure values are 64-character hex strings.

    • API returns 400 and bad_records if format is incorrect.

  3. Payload Too Large

    • Limit is 10MB. Split into smaller batches or gzip the payload.

    • Use Content-Encoding: gzip when sending compressed data.

Audience Expiry: Common Errors

  1. Mismatched IDs

    • The segmentId in JSON must match the one in the URL.

  2. Segment Already Archived

    • Archived segments cannot be reactivated via API. Check status before calling.

Cross-Audience Opt-Out: Common Errors

  1. Invalid Hash or IP Format

    • SHA-256 or IPv4 values must follow strict format validation.

    • API returns detailed error messages if format fails.

  2. Empty Payload

    • At least one identifier (email, IP, etc.) must be included. Empty arrays will be rejected.

  3. Missing Opt-Out Keys

    • Request must include at least one of: email_sha256, ip, mobile_id, or cookie.