Copy page

Best practices

Avoid Common Mistakes

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 4xx errors as-is

A 4xx response means the request cannot succeed 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	Daily quota reached	Wait for Retry-After, then retry (see below)

Wait for Retry-After on 429

API calls are subject to daily quotas. When one is reached, the API answers 429 Too Many Requests until the quota resets at midnight:

Code
HTTP/1.1 429 Too Many Requests
Retry-After: 35999
Content-Type: application/json

{ "error": "quota_exceeded", "message": "Too many requests", "retry_after": 35999 }

The Retry-After header and the retry_after field hold the same value: the number of seconds until the quota resets. Rely on this value rather than on your own clock, and do not retry before this delay: a refused call still counts against the quota, so retrying sooner only keeps you blocked. The daily limit of trends extracts (POST /extracts) answers the same way, with the message Limit reached today for trends extracts.

Code
class SyncJob < ApplicationJob
  rescue_from ApiError do |e|
    raise e unless e.status == 429

    # Defer the job instead of sleeping: the quota may only reset hours later.
    retry_job(wait: e.body.fetch('retry_after').seconds)
  end
end

Use exponential backoff for 5xx

Transient server errors can be retried, but with increasing delays between attempts. Keep 429 out of this loop: a quota does not come back after a few seconds, so stop and schedule the next call after Retry-After.

Code
def with_backoff(max_retries: 5)
  retries = 0
  begin
    yield
  rescue ApiError => e
    raise unless e.status >= 500 && 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.