Skip to the content
Get an API key
  1. API reference
  2. Webhook events

transfer.failed

Managed TransfersDeliveryPOST to your endpoint

Sent with the headers X-MusicAPI-Event: transfer.failed and X-MusicAPI-Signature: t=<seconds>,v1=<hex HMAC-SHA256 of "t.body">.

Headers

Content-Type

application/json

X-MusicAPI-Event

The event name, for example transfer.completed.

X-MusicAPI-Signature

t=<seconds>,v1=<hex>. The hex is the HMAC-SHA256 of <t>.<raw body> with your endpoint secret.

Payload

id
string
The id of this delivery, evt_<uuid>. A retry sends the same id, so dedupe by it. Two endpoints get two different ids for the same event. Deliveries queued before 2026-10-16 have no id.
event
string
requiredOne of: transfer.failed
createdAt
date-time
required
data
object
required
data.transferUuid
uuid
required
data.status
string
data.totalItems
number
data.processedItems
number
data.matchedItems
number
data.unmatchedItems
number
data.skippedItems
number
data.failedItems
number
data.sourceIntegrationType
string
data.targetIntegrationType
string
data.resultsUrl
uri
The Match Results API address of the unmatched items.
data.stage
string
Only when the transfer failed before it finished: the stage that failed.
data.error
string
Our internal error text. It can change and is not written for end users: show failureReason instead.
data.errorType
string | null
data.endUserId
string | null
Your own id for the person: the externalUserId of the session, else the merchantUserId of the source login. Null when you sent neither.
data.batch
TransferWebhookBatch | null
The batch of the transfer. Null for a transfer that was made alone.
data.batch.uuid
uuid
required
data.batch.size
number
requiredHow many transfers the batch holds.
data.batch.endedTransfers
number
requiredHow many of them ended (completed, completed with errors, failed or cancelled).
data.batch.complete
boolean
requiredTrue when every transfer of the batch ended. The event is then the last one of the batch. Two transfers that end at the same moment can both say true, so dedupe your batch notice by uuid.
data.batch.notifyWhenDone
boolean | null
requiredThe notifyWhenDone option of the create call. Null when the call did not send it.
data.batch.completedTransfers
number
requiredThe transfers that ended well (completed or completed with errors).
data.batch.failedTransfers
number
requiredThe transfers that failed or were cancelled.
data.batch.matchedItems
number
requiredThe sum over the transfers that ended well.
data.batch.totalItems
number
requiredThe sum over the transfers that ended well.
data.batch.failedItems
number
requiredThe sum over the transfers that ended well.
data.batch.progress
TransferWebhookBatchProgress
requiredHow far the whole batch got, over every transfer of it (running ones too).
data.batch.progress.processedItems
number
requiredItems processed, summed over every transfer of the batch.
data.batch.progress.totalItems
number
requiredItems to process, summed over every transfer of the batch.
data.batch.progress.pct
number
required0 to 100, rounded down. 100 only when every item was processed.
data.errorName
string
Only when the transfer failed before it finished: the class name of the error. For a bug report or a dashboard, not for a branch.
data.failureReason
string
Why the transfer failed, in a value you may branch on. notAuthenticated: an account was signed out and could not be recovered. rateLimited: a music service asked us to slow down too often; the same transfer would work later. targetRefused: the transfer ran to the end, but the destination refused its playlists or items. unknown: anything else.One of: notAuthenticated, rateLimited, targetRefused, unknown
data.failureSide
string | null
The end of the transfer that failed. Null when we cannot tell.One of: source, target, null

Delivery and retries

Answer with a 2xx status. We try other answers again, up to 5 attempts in total. The waits between attempts are:

  • 60 s
  • 120 s
  • 240 s
  • 480 s

Set up the endpoint and its secret in the guide Set up and verify.