API operations at scale often return errors instead of successfully completing a given request. The BigCommerce API has two primary classes of error messages that can impact data migration: 4xx and 5xx.
For an in-depth list of the various status codes, including errors, and what they mean, see API Status Codes.
5xx status codes indicate server-side issues. These errors generally cannot be resolved by the client. For transient errors such as 500, 502, 503, or 504, implement exponential back-off retries, up to a set limit (e.g., 10 attempts), increasing the wait time between each retry. However, other 5xx errors like 501 or 505 are persistent and should be logged and investigated rather than retried.
While rate limiting typically returns a 429, you may occasionally receive a 500 for similar scenarios. Handle these with the same retry strategy. For more on handling server errors, see API Request Architecture.
4xx errors indicate malformed requests or invalid data. For automated operations, log and skip most 4xx errors for later review, but note that some require immediate attention.
Logging and skipping errors can lead to silent data loss. Always review error logs post-migration and generate a summary of skipped records for follow-up.
Implement robust rate limiting for automated API calls to avoid exceeding platform rate limits.
429The API returns this error when you exceed the platform rate limits.
429 status, it will likely return 429 for subsequent requests unless the rate limit window elapses.429 status in your response, use either the X-Rate-Limit-Time-Reset-Ms or the X-Retry-After header from the response to wait before retrying the request.If both X-Retry-After and X-Rate-Limit-Time-Reset-Ms are present, honor the longer of the two wait times.
404The API returns this error either when a request’s path does not match an existing endpoint, when a provided parameter does not match existing data, or less commonly when the method of the request is invalid.
404 status is returned for individual API calls, this usually means that some referenced data does not match existing data. In general, this should be logged and skipped, including the exact path, body, and response of the request to investigate the cause later.When employing batch endpoints, for example Update Products (Batch), there may be a single item that causes the whole request to fail. Often, the response for batch endpoints will include the index of the failed item. Use this index to remove the item from the request, then retry.
Not every batch endpoint identifies the index or indices of failed items. If the response doesn’t specify which items failed in a batch request, you’ll need to send each item in separate requests to identify and report the failures.
Do not assume the entire batch succeeded or failed. Process successful items, and retry or log errors for failed ones.
422The API returns this error when a request is formatted incorrectly or contains invalid data.
422 error should typically only occur during testing. If you see it during a large data migration, check your dataset and the data mapping for potential problems.422 error. However, repeated 422 errors indicate a persistent problem that you must fix before continuing the migration.Implement thorough client-side validation before sending API requests. If you encounter repeated 422 errors during production data migration, treat this as a critical issue. Pause the migration, fix the data mapping, and only resume once the problem is resolved.
Below is an example of a malformed request to the endpoint Update Products (Batch). Due to the requirements of the endpoint, a 422 status code is expected from this request.
Use exponential backoff for retrying transient errors, starting with a short delay and doubling it after each failed attempt, up to a maximum number of retries (e.g., 10). Add a small random jitter to each delay to reduce collision risk. Always respect any X-Retry-After or other rate limit headers from the response.
Monitor response headers such as X-Rate-Limit-Requests-Left, X-Rate-Limit-Time-Reset-Ms, and X-Retry-After. These indicate how many requests remain and when you can resume making requests. Adjust your request rate accordingly to avoid being throttled or blocked. For more information, see BigCommerce Specific Headers
Repeated 422 errors suggest a problem with your data or mapping logic. Pause your migration, review your data transformation, and ensure all required fields and formats match the API’s expectations before resuming.
Implement generic error handling for network issues and timeouts. Retry failed requests using exponential backoff, and ensure your code checks for and gracefully handles situations where no response or a malformed response is received.