Troubleshooting

Find the symptom, try the fix. If nothing here helps, contact support with the request_id.

The first call fails

401 "Missing credentials". The Authorization header did not arrive. Check that the environment variable is set in the shell or process that runs the request (echo ${POPNOW_API_KEY:0:10} should print sk-popnow-), and that a proxy or HTTP library is not dropping the header.

401 "Key format is not recognized". The value is not a PopNow key — often a copy of something else from the clipboard. Keys start with sk-popnow-.

401 "Credentials are invalid or expired". The key was revoked, expired, or mistyped. Create a new one in the API console.

40310. Your account's email address is not verified. Open the link from your sign-up email; the key starts working immediately afterwards.

40201 "Insufficient balance". The account does not have enough credits for this task's hold. Video holds can be large; check the price with jobs/quote and buy credits.

The request is rejected

400 naming a field. The input does not match the model's schema: a misspelt field, a value outside the allowed list, or a missing required field. Open the model's reference page from Models and compare.

400 "Invalid callback URL". The callBackUrl must be public HTTPS, on port 443, with no username or password. localhost and private addresses are refused.

40004. The model is working but cannot serve this exact combination of settings right now. Change the setting named in msg (often resolution, duration or aspect ratio).

50301. The model is temporarily unable to take tasks. Retry later or pick another model.

413. The JSON body is over 2 MiB, usually because of inline images. Upload them instead.

The task fails

invalid_asset. A reference file could not be fetched or read. Open the URL in a private browser window: it must download the file itself, without a login. Share pages from cloud drives do not work.

content_rejected. The model declined the prompt or a reference image. Rephrase, use different references, or try another model.

timeout or expired. The job took longer than allowed. Try a shorter duration or lower resolution.

generation_failed. The model ran but produced nothing. The same input often fails again; change the prompt or the settings.

Failed and expired tasks do not use credits.

The result

The download link returns 403 or "expired". Signed links last about 20 minutes. Read the task again with recordInfo for a fresh link.

The download link fails when I send my API key. Do not send Authorization to the signed link; the link itself is the permission.

recordInfo returns 404 for a task I created. Tasks are visible only to the key that created them. Use the same key, or look the task up in the API console.

Webhooks

Nothing arrives. Check that the URL is reachable from the internet over HTTPS, that your firewall allows it, and that your handler answers 2xx within 15 seconds. Failed deliveries are listed in the API console.

The signature never matches. Hash the raw body bytes, not a re-serialised JSON object; use data.taskId, the X-Webhook-Timestamp header, and the secret you generated most recently.

The same task arrives twice. That is expected after a retry. Ignore duplicates by request_id.

Uploads

The PUT returns 403 from storage. A header differs from the ticket. Send Content-Type and Content-Length exactly as given, and no Authorization header.

Commit returns 40003. The file you uploaded does not match what you declared. Request a new ticket with the right contentType and bytes.

Commit returns 409. The ticket expired (after about 20 minutes). Request a new one right before uploading.