Rate Limits and Retries

Enterprise integrations should assume that every API call can fail, time out, or complete after the client has already lost the connection. The safest client is state-driven: it reads the current resource state before repeating high-impact actions.

Baseline client rules

Situation	Required client behavior
Read request fails with `408`, `429`, or `5xx`	Retry with exponential backoff and jitter.
Token request fails	Request a new token only when the previous request clearly failed or the token is expired.
Create request times out	Search or fetch by the business data you already sent before creating another record.
Upload request fails before a response	Retry the same file or chunk. Use the returned `audio_file_id` only after a successful upload response.
Submit request times out	Fetch the release and review state before submitting again.
Checkout request times out	Check whether a `checkout_id` was returned or whether the related order state changed before creating another checkout.
Add-on install or purchase times out	Read the add-on status before repeating the action.

Rate limit handling

The API can return 429 when a client sends too many requests or repeats expensive operations too quickly.

Protected API requests use all of these rolling one-minute limits:

Dimension	Limit
API client	600 requests
Organization	1,200 requests
Source address	180 requests

The first exhausted limit stops the request. DDEX requests additionally allow 300 requests per client and 120 per connection each minute. Direct audio uploads allow 10 requests per user, 100 per organization, and 20 per source each minute. Chunk uploads allow 90, 900, and 180 respectively. Token exchange has tighter credential and source limits to resist guessing attacks.

When you receive 429:

Stop sending the same request immediately.
If the response includes Retry-After, wait at least that long.
If no retry value is included, wait with exponential backoff.
Keep request bursts below the level that caused throttling.
Prefer list endpoints and batch-friendly workflows over tight per-record polling loops.

Recommended backoff:

Attempt	Minimum wait
First retry	2 seconds
Second retry	5 seconds
Third retry	15 seconds
Later retries	30 to 60 seconds with jitter

If an integration needs sustained high-volume ingestion, agree the expected volume during onboarding instead of relying on aggressive retry loops.

Retry safety by operation type

Operation type	Auto retry?	Why
`GET` list or view	Yes	Reads do not create duplicate catalog, billing, or access changes.
`POST /api/v1/token`	Conditional	Safe when the previous token is expired or unavailable. Store only the latest usable token.
Create artist, user, release, track, member, smartlink	No	A repeated request can create duplicate records unless the endpoint explicitly documents duplicate prevention.
Update metadata	Conditional	Retry only when the same update can be safely applied again and no conflicting operator change happened.
Upload audio or documents	Conditional	Retry the same file or failed chunk. Do not attach an `audio_file_id` until upload success is confirmed.
Release submit	No	Read release and review state before retrying. Submission can lock or move the release into review.
Checkout creation	No	A repeated request can create duplicate payment attempts. Store and verify `checkout_id`.
Wallet top-up	No	Read checkout or wallet transaction state before creating another payment attempt.
Add-on purchase, install, activate, deactivate, uninstall	No	Read add-on state before repeating.
Theme publish or email theme publish	Conditional	Retry only after reading the current published state.

Idempotency keys

There is no global idempotency key documented for every endpoint. If an endpoint supports an idempotency key, the endpoint reference must say so directly.

Until then:

Generate a client-side operation reference in your own system.
Store the request body, timestamp, acting user, and target public reference.
On timeout, read the target resource before retrying.
For create actions, search for a matching record before creating another one.
For checkout actions, keep the first checkout_id and verify it instead of creating a second checkout.

Polling guidance

Polling should be slow, bounded, and state-aware.

Workflow	Suggested polling pattern
Release readiness	Poll only after metadata or asset changes. Stop once no blocking issue remains.
Submitted release review	Poll release review queues every 30 to 60 seconds while an operator is waiting. Use longer intervals for background sync.
Delivery status	Poll sent or delivered release queues every few minutes. Delivery can depend on downstream systems and should not be treated as instant.
Checkout verification	Poll after user returns from checkout or when a payment screen reports a pending state.
Upload processing	Poll only when the upload endpoint or follow-up endpoint returns a pending state.

Support escalation data

When retry behavior is unclear, provide support with:

Endpoint and HTTP method.
Public reference such as release_id, track_id, checkout_id, or user_id.
Request timestamp and timezone.
Response status and message.
Whether the request was retried.
Whether the related resource changed after the timeout.

Do not send API secrets, bearer tokens, payment provider references, or raw customer credentials in support messages.

Common questions

Which limit did I hit? The first one exhausted stops the request: 600 per minute per API client, 1,200 per organization, or 180 per source address. DDEX, upload, and token endpoints have their own tighter limits.

Is there an idempotency key? Not globally. If an endpoint supports one, its endpoint page says so. Until then, read the target resource before repeating a write.

My create request timed out. Should I send it again? No. Search for a matching record first. A blind retry is the most common cause of duplicate releases and duplicate payment attempts.

How aggressively can I poll? As slowly as your workflow tolerates. Tight per-record polling loops are the fastest way to hit a rate limit; prefer list endpoints.

I need sustained high-volume ingestion. What now? Agree the expected volume during onboarding rather than building an aggressive retry loop around the limits.