Error Responses#

HTTP status	Meaning	Recommended action
`400 Bad Request`	The request body or query parameters are invalid.	Correct the request before retrying.
`401 Unauthorized`	Credentials are missing, invalid, expired, or not active.	Verify the authentication headers or contact Ideal House.
`403 Forbidden`	The requested `shopId` is not associated with the credentials.	Use the Shop ID assigned to the credentials.
`404 Not Found`	No import status or matching product is available.	Verify the Shop ID and the requested Product ID or SKU.
`409 Conflict`	Another import job is active for the shop.	Wait for the current import job to finish.
`429 Too Many Requests`	The request rate is too high.	Retry with exponential backoff and jitter.
`500 Internal Server Error`	The service encountered an unexpected error.	Retry with exponential backoff. Contact Ideal House if the error persists.
`502 Bad Gateway` or `503 Service Unavailable`	The API is temporarily unavailable.	Retry with exponential backoff.

A validation error may use the following format:

json

{
  "message": ["shopId should not be empty"],
  "error": "Bad Request",
  "statusCode": 400
}

The text in message may vary. Use the HTTP status code and documented response fields for program logic.

Retry and Recovery Guidance#

Poll every 2 to 5 seconds while a job is pending or running.
For 429, 500, 502, and 503 responses, use exponential backoff with jitter and set a maximum retry limit.
Do not automatically retry 400, 401, or 403 responses without correcting the request or credentials.
After 409, wait for the active job to reach completed or failed.
If a submission times out before you receive a response, query the status endpoint before submitting the batch again.
Retrying the same product with the same SKU is safe because imports use create-or-update behavior.
After a completed job with item-level failures, submit a new batch containing only the failed products.
After a job-level failure, products counted in successCount may already have been updated. Resubmitting the original batch with the same SKUs is safe.
A deletion may already have taken effect even if the request returns 503. Retrying the same deletion request is safe.

The status endpoint is intended for tracking the active or most recent job, not for permanent import history. Store the submitted batch, jobId, status responses, and final outcome in your own system for reconciliation and support.

Production Checklist#

Store the Client Secret in a secrets manager or protected server environment.
Use a stable, unique SKU for every product.
Send no more than 500 products per request.
Ensure image URLs are publicly reachable and remain available during processing.
Explicitly set processImages: true only when image preprocessing is needed and the associated 1-credit-per-image processing charge is accepted. Otherwise omit it or set it to false.
Enable Floor splitting only by setting both processImages and processFloorImages to true.
Provide name, imageUrl, productUrl, width, height, and a supported productType for every product.
When provided, set status to active, inactive, out_of_stock, or invalid.
Send dimensions as positive values with a supported unit, or omit the unit to use inches; stored values are normalized to inches.
Persist the returned jobId and compare it with subsequent status responses.
Treat completed with failedCount > 0 as a partial success.
Paginate through the product list instead of requesting an unbounded catalog.
Provide exactly one of productId or sku for delete operations.
Implement bounded retries with exponential backoff and jitter.

For credentials, onboarding values, product-type mapping, or persistent integration issues, contact your Ideal House integration representative.