Best practices

Avoid Common Mistakes

Copy page

These are the most frequent misuses we observe that can affect the reliability of your integration.

File size limits

Binary files embedded as data URIs (base64) must not exceed their documented size limits before encoding.

Resource	Field	Maximum size
Products	front-cover	20 MB

Submitting a file that exceeds the limit will return a 422 Unprocessable Entity. Compress or resize the file before sending it. You can verify the file size before encoding:

Code
file_size_mb = File.size("cover.jpg") / 1_000_000.0
raise "Cover exceeds 20 MB limit" if file_size_mb > 20

Only use documented endpoints

Only endpoints documented in this dev center are part of the public API and covered by our stability guarantees. Any other endpoint you may discover is internal and subject to change or removal without notice.

Accounts found using private or undocumented endpoints without prior written permission will be suspended.

If you have a use case that requires access to data or functionality not currently exposed in the public API, please contact us.

Retry strategy

Do not retry on 4xx errors

A 4xx response means the request is invalid as sent. Retrying the same payload immediately will return the same error every time.

Status	Cause	Correct action
401 Unauthorized	Token invalid or expired	Refresh your access token, then retry
422 Unprocessable Entity	Validation failure	Fix the request data before retrying
429 Too Many Requests	Rate limit hit	Wait and retry with backoff (see below)

Use exponential backoff for 5xx and 429

Transient server errors and rate limit responses can be retried, but with increasing delays between attempts:

Code
def with_backoff(max_retries: 5)
  retries = 0
  begin
    yield
  rescue ApiError => e
    retryable = e.status >= 500 || e.status == 429
    raise unless retryable && retries < max_retries

    wait = 2 ** retries  # 1s, 2s, 4s, 8s, 16s
    sleep(wait)
    retries += 1
    retry
  end
end

Do not send concurrent writes to the same resource

Sending multiple simultaneous POST or PUT requests targeting the same resource (same product ID, same track ID) causes race conditions. Ensure writes to a given resource are sequential — limit concurrency to one in-flight write per resource at a time.