Errors#

Both APIs answer a failed request with an HTTP error status and a JSON body whose top-level error object uses the same field names: code, message, details[] and request_id. That is where the resemblance ends. They are two error models, not one:

• the codes are separate lists — a code means what its own API says it means;
• the Partner API's bulk endpoints report rejected rows inside a 200; the Checkout API has no batch endpoints;
• both replay retries — a repeated Idempotency-Key with the same body gets the stored response back, with Idempotent-Replayed: true.

Branch on code, never on message, and log request_id on every failure: it is what Povito support needs to trace a call on either API.

The envelope, side by side#

{
  "error": {
    "code": "validation_error",
    "message": "items cannot exceed 50 rows per request.",
    "details": [{ "field": "items", "issue": "too_many" }],
    "request_id": "req_01J..."
  }
}

{
  "error": {
    "code": "amount_mismatch",
    "message": "Line items net to 44000 but amount is 45000.",
    "details": [{ "field": "line_items", "issue": "sum_differs" }],
    "request_id": "req_5c1b0a4e-2f6d-4a0b-9d3e-7b8c1f2a3d4e"
  }
}

Per-row results: read results[]#

This is the Partner API's one behaviour with no Checkout counterpart. POST /products/bulk and PATCH /inventory/bulk handle each row on its own and answer 200 even when some rows are rejected; a rejected row carries its own error:

{
  "results": [
    { "external_sku": "ERP-1042", "status": "accepted", "product_id": "prod_01J..." },
    {
      "external_sku": "ERP-1043",
      "status": "rejected",
      "error": { "code": "validation_error", "message": "title and price_iqd are required to create a new SKU." }
    }
  ]
}

A top-level 4xx means the whole request was wrong; a rejected row inside results[] means that one SKU was. Treating "HTTP 200" as "everything synced" is the most common Partner API integration bug.

Status codes#

Retrying safely#