Errors & Troubleshooting

Every MultiCartAPI response arrives as HTTP 200 — business-logic errors are signalled by status: 0 inside the envelope, not by the HTTP status code. This page covers the most common failure patterns and how to resolve them.

Error response shape

When a call fails, the envelope looks like this:

{
  "code": 402,
  "data": "Not enough credits — you need 250 but have 12 remaining.",
  "status": 0
}

code carries the intended HTTP-style error class. data is a human-readable string explaining the specific problem. The outer HTTP status is always 200.

Common errors quick reference

Insufficient credits (402)

Collection run

When you call POST /api/v1/schedules/run/result/ the API gates on your credit balance before queuing anything. If available_credits - used_credits - frozen_credits is less than the number of items in the collection, the run is rejected immediately.

Response:

{
  "code": 402,
  "data": "Not enough credits — you need 250 but have 12 remaining.",
  "status": 0
}

Fix:

• Check your balance with POST /api/v1/users/credits/.
• Either upgrade your plan, wait for your credit period to reset, or reduce the collection size before re-running.

Playground endpoint

The Playground (POST /api/v1/playground/post/) behaves differently. It returns status: 1 (success envelope) but the credit check failure is buried inside the output payload:

{
  "code": 200,
  "data": {
    "type": "json",
    "output": {
      "error": "Insufficient Credits"
    }
  },
  "status": 1
}

Fix: Check data.output.error after every Playground call. If it equals "Insufficient Credits" your balance is zero — replenish credits before continuing.

Duplicate conflicts (409)

The API rejects two classes of duplicate:

Duplicate postcode

If you call POST /api/v1/zipcodes/create-zipcode/ with a postcode that already exists for that user + domain combination, you receive:

{
  "code": 409,
  "data": "Zipcode already exists for this domain.",
  "status": 0
}

Fix: Fetch your existing postcodes with POST /api/v1/zipcodes/get-zipcodes/ and reuse the existing record's id — no need to create a duplicate.

Duplicate ASIN

If you add an ASIN via POST /api/v1/schedules/amazon/asin/create/ and the exact combination of collection + domain + customer_postcode + asin already exists, the request is rejected as a duplicate. The response returns status: 0 with an explanatory message in data:

{
  "data": "ASIN already exists in this collection.",
  "status": 0
}

Fix: Each ASIN entry is unique per collection + domain + postcode tuple. If you need the same ASIN scraped against a different postcode, create a separate entry with that postcode's zipcode ID. When bulk uploading via /asin/create/multiple/, duplicate rows are reported in data.error_rows — the remaining rows still succeed.

Missing cookie for category scrape (400)

Amazon category scrapes (POST /api/v1/schedules/amazon/category/add_schedule/) require a valid cookie file for the requested domain + postcode before the job can be queued. If no active cookie exists, the endpoint returns:

{
  "code": 400,
  "data": "No cookie file found for domain amazon.com.au postcode 4500. Please add the postcode and wait for it to become active.",
  "status": 0
}

What causes this: Cookie files are generated asynchronously after you add a postcode. Submitting a category scrape before cookie generation finishes (or for a postcode you haven't added yet) triggers this error.

Fix:

1. Add the postcode if you haven't already — POST /api/v1/zipcodes/create-zipcode/.
2. Poll POST /api/v1/zipcodes/get-zipcodes/ until the postcode's status field is "active".
3. Retry the category scrape.

See Postcodes for a full explanation of postcode statuses, and Category Scrape Guide for the end-to-end workflow.

Generic status: 0 failures

For any other status: 0 response, read the data field — it always contains a plain-English description of what went wrong. Common examples:

General debugging checklist:

1. Confirm body.status === 0 before treating a response as an error.
2. Log body.code and body.data — they are always populated on failure.
3. Check that you are passing the correct field names — several endpoints have subtle naming differences (for example, schedule_id vs collection_id). See the API Reference for exact field names per endpoint.
4. Verify your x-api-key header is present and correct on every authenticated call.

Error Logs in the dashboard

The dashboard includes a dedicated Error Logs view that surfaces scraping-level errors (for example, a postcode cookie that failed to regenerate, or a domain-level scrape failure). These are distinct from API-level errors and provide more detail about what happened during individual scrape runs.