Troubleshooting API cache requests

quick triage checklist

Confirm endpoint is POST https://www.node-modules-cache.com/api/v2/npm/ci with Authorization: Bearer <token>.
Confirm payload keys exactly match dockerImageReference, architecture, package.json, and package-lock.json in an application/json body.
Confirm your client follows redirects (--location for curl) and writes node_modules.tar.gz.
Keep a fallback to npm ci so deployments continue during misses or transient errors.

error reference

401 Unauthorized

The token is missing, invalid, or no longer active. Reissue a token in your dashboard, store it as NMC_ACCESS_TOKEN in CI secrets, and verify the header is exactly Authorization: Bearer <token>.

422 Unprocessable Entity

Request shape does not match the API contract. Validate payload keys, ensure architecture is x64 or arm64, and confirm both manifest objects are valid JSON documents.

429 Rate limit exceeded

You reached the first-run build quota for your plan window. Cache hits remain unlimited, but misses are limited by daily/monthly allowances. Keep fallback npm ci enabled and retry after reset or upgrade your plan on the pricing page .

500 Cache processing failed

This is usually transient. Retry once, then fall back to npm ci to unblock the pipeline. If failures persist, share timestamp and request context via contact .

Redirect not followed / archive missing

Success returns 302 Found with a Location header. If redirect-follow is disabled, your client will not download the archive.

Shell / curl — follow redirect

curl --request POST "https://www.node-modules-cache.com/api/v2/npm/ci" \
  --header "Authorization: Bearer ${NMC_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  --location \
  --output node_modules.tar.gz

tar -xzf node_modules.tar.gz

Troubleshooting