Errors

All errors follow:

{
  "error": {
    "code": "invalid_query_parameter",
    "message": "Human-readable summary."
  },
  "meta": { "requestId": "..." }
}

Always cite meta.requestId when reporting issues to Soundlink. OAuth protocol endpoints (/api/v1/oauth/*) do not use this envelope. See OAuth scopes and errors. Using the TypeScript SDK? API errors arrive as { data: null, error } on every method — see Access the API with TypeScript. Thrown SoundlinkSdkError subclasses are only for config, parse, and transport failures.

Common codes

HTTP	Code	When
401	`invalid_api_key`	Missing `Authorization: Bearer`, or API key not recognized
401	`invalid_token`	Invalid or expired OAuth access token
401	`api_key_revoked`	Key revoked
401	`api_key_expired`	Key past `expires_at`
403	`insufficient_scope`	Valid credential missing the route scope
404	`not_found`	Unknown path, or a soundlink that is missing, in another organization, linked to a campaign, or not `active` on archive
404	`campaign_not_found`	Unknown campaign or other org’s campaign
400	`invalid_query_parameter`	Bad pagination or sort params
400	`invalid_date_range`	`endDate` before `startDate`
400	`page_size_exceeded`	`pageSize` above endpoint max
429	`rate_limit_exceeded`	Rate limit exceeded (honor `Retry-After`)
500	`internal_error`	Unexpected failure — retry with backoff

Write endpoint codes

Returned by campaign creation and management routes (campaigns:write). See Creating campaigns and Managing campaigns.

HTTP	Code	When
400	`invalid_request`	Missing/malformed body field, missing `Idempotency-Key`, non-wallet campaign, or a decrease rule violated
400	`invalid_tier_status`	Tier update items invalid (missing tiers, sum ≠ 100, none enabled)
402	`insufficient_credit`	Wallet balance too low — `details.available` / `details.required`
403	`wallet_not_enabled`	Organization not enabled for wallet billing
409	`idempotency_key_conflict`	`Idempotency-Key` reused with a different body, or still processing
409	`learning_edit_ack_required`	An active tier is `LEARNING` or `FAIL` within 72 hours, and `acknowledgeLearningWarning` is not `true`. `details.tierIds` lists those tiers.
422	`invalid_genre`	Genre not in the supported list
422	`invalid_daily_budget`	`dailyBudget` below $10/day
422	`invalid_duration_days`	`durationDays` outside 7–30 and not 60/90
422	`invalid_spotify_url`	Malformed Spotify URL, or track/playlist does not exist
422	`invalid_tier_budget_allocation`	Tier percentages invalid (sum, count, or per-tier minimum)

Soundlink create codes

Returned by POST /v1/soundlinks (soundlinks:write). See Creating soundlinks.

HTTP	Code	When
400	`invalid_request`	Missing/malformed field, invalid `appleMusicUrl` or `youtubeMusicUrl`, Meta pixel token without ID or unowned pixel ID, `attributionEnabled: false` with `autoFollow: true` or with `streamValueEventEnabled: true`, or missing `Idempotency-Key`
403	`soundlink_plan_required`	Organization has no Self-Serve plan
403	`stream_value_not_enabled`	Organization is not enabled for Soundlink Stream Value
409	`idempotency_key_conflict`	`Idempotency-Key` reused with a different body, or still processing
422	`invalid_spotify_url`	Malformed Spotify URL, or track/playlist does not exist

Pixel codes

Returned by /v1/pixels (pixels:read / pixels:write). See Managing pixels.

HTTP	Code	When
403	`custom_pixel_not_enabled`	Organization does not have custom pixels enabled
409	`meta_pixel_conflict`	Pixel is owned by another organization
409	`pixel_in_use`	Delete blocked because a soundlink still uses the pixel (`details.smartLinkCount`)

Video import codes

Returned by video import routes (videos:write). See Importing videos.

HTTP	Code	When
400	`invalid_video_url`	Not HTTPS, unreachable, over 70 MB, or download timed out
400	`invalid_video_content_type`	Unsupported format
403	`video_import_limit_exceeded`	Plan video quota or organization storage limit exceeded
404	`video_import_session_not_found`	Unknown session or another organization’s session
429	`rate_limit_exceeded`	Stricter import cap (honor `Retry-After`)

Rate limits

Default limits are 60 requests/minute and 600 requests/hour, counted per API key or OAuth client. Video import is a separate cap: default 20 imports/hour per API key or OAuth grant. Honor Retry-After.

Pagination limits

Campaign and soundlink lists: pageSize max 100
Metrics breakdown and engagement lists: pageSize max 500 (see endpoint docs)

Get started

AI tools

For Developers

Learn