Errors

​

Status codes

​

Validation error shape

{
  "detail": [
    {
      "loc": ["body", "items", 0, "regular_price"],
      "msg": "field required",
      "type": "missing"
    },
    {
      "loc": ["body", "items", 1, "observed_at"],
      "msg": "input should be a valid datetime",
      "type": "datetime_parsing"
    }
  ]
}

• loc - JSON path to the offending field, including array indices.
• msg - human-readable message.
• type - machine-readable error code (e.g., missing, string_too_long, value_error).

​

Bulk endpoints: per-item errors

{
  "results": [
    { "index": 0, "ok": true,  "id": "1c2d..." },
    { "index": 1, "ok": false, "code": "validation_error", "message": "product_name too long" }
  ]
}

​

Common 422 cases by endpoint family

• Products - missing item_id, missing sku, or a decimal field that can’t parse.
• Product store - missing item_id, store_id, or current_price; store_id referencing an unknown store.
• Transactions - missing item_id, malformed transaction_timestamp, decimal field that can’t parse.
• Competitor prices - missing one of the four required fields (competitor_name, observed_at, regular_price, effective_price).
• Imports (CSV) - file not attached, file empty, file not UTF-8, header row missing.

​

Retry strategy

• Idempotent endpoints (POST /v1/<entity>/{entity_id}, PATCH, DELETE, /bulk) - retry on 5xx and on transport errors with exponential backoff (start at 1s, cap at 30s, max 5 attempts).
• POST /v1/competitor_prices - this is a non-idempotent create (no path id). Retrying after a successful response will create a duplicate row. Check the network outcome before retrying.
• Async imports - if POST /v1/imports/* fails, retry the upload. If it succeeds and the subsequent job fails, fix the CSV and submit a fresh job rather than retrying the same upload.