Errors, retries and credit
Interpret upload outcomes and retry safely without changing the observation.
Results and retries
A successful HTTP status is not proof of contributor credit—or of a merge. Inspect reason alongside credited.
| Outcome | Client action |
|---|---|
200 · credited: true | Merged and credited. No retry. |
200 · incomplete / too_small / too_soon_credit | Eligible readings merge without credit. No retry; do not resubmit the same data to seek credit. |
200 · disagrees | Quarantined for review, not merged. Check market, variants, units and source data before sending more. |
200 · duplicate | This market and observation timestamp are already stored. No retry. |
400 · bad_book / bad_via | Fix the schema, sort order, counts, timestamp, encoding or partner ID. Oversized books also return bad_book. |
401 / 403 | Check credential, deployment and required feature. Browser sessions cannot upload. Do not retry unchanged credentials indefinitely. |
404 · retired scan upload | Migrate the producer to real auction books. Summaries cannot reconstruct missing auction detail. |
409 · too_soon | Wait five minutes before retrying this file. The new-book interval is per caller and market. |
429 · rate_limited | Wait the number of seconds in Retry-After, then retry with backoff and jitter. |
Network failure / 5xx | Retry the same file with exponential backoff and jitter, within the original 24-hour observation window. Storage failures must not cause a new timestamp. |
{"error":"forbidden","feature":"api.upload"}Contributor credit
A complete book needs at least 100 priced item keys or 25% of the recently listed market, agreement with other accounts’ recent readings when enough exist, and no credited upload by the account for that market in the last 5 minutes. Credit extends contribution access for 14 days. Device/key upload intervals and account credit intervals are separate.
Request limits
Request limits are 60/minute for anonymous callers, 120/minute for free accounts, and 600/minute for contributors and premium accounts. Your effective limits appear in /me. The five-minute book-upload interval applies separately.
Reliable retries
Persist the original book before sending. Reuse the same credential, market and at on retries; stop after an accepted outcome. A timeout may have happened after the server stored the book, so retry the original request instead of constructing a new observation. An Idempotency-Key header is not part of this API’s contract.
Versioned contracts and runnable examples live with the source specification →.