# 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:

```ruby
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:

```ruby
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.