Almost every failed S3zipper request has one of a handful of causes. Here is what each response means and how to fix it — useful when you are wiring the API into a script or an application.
HTTP 401 — missing or invalid token
The Authorization: Bearer header is absent, malformed or expired. Get a fresh token from /gentoken and retry. Tokens last a day.
AWS Credentials(Key, Secret or Token) Error
The AWS key and secret you passed cannot read the bucket. Check that they are valid, not expired, and have permission to list and read the prefix you asked for. Temporary credentials also need their session token in awsToken.
NoKeys Found Error
filePaths was empty, or none of the paths resolved to an object. Paths are full S3 keys — my-bucket/folder, not folder.
FILE GET ERROR
A path was found but could not be read. Common causes: a typo in the prefix, a key that exists only in another region, or a bucket policy that blocks reads.
Limits Error Found
The archive is larger than your plan allows per request. Zip a smaller prefix, split the job, or upgrade the plan. Admins are exempt from limits, which makes them useful for testing.
Validate Error Found
A field failed basic validation — most often an invalid email address in resultsEmail.
Invalid TaskID
The state or result call carried a task id that does not exist (or is not a valid id). Replay the original start response rather than hand-editing the task id.
NOT-STARTED
The job could not be queued — a transient backend problem. Retry after a short pause; do not treat it as a data error.
HTTP 413 — request too large
Request bodies are limited to 2 MB. If you send thousands of paths, put the list in an object in your bucket and pass its key in filePathsLocation instead.
HTTP 429 — too many requests
Rate limits protect the service. Back off and retry; if your workload is genuinely high, talk to us about it.
Debugging checklist
- Did you get a token, and is it still valid?
- Are the AWS credentials valid for this bucket and region?
- Do the paths include the bucket name?
- Is the total size within the plan?
- Did you replay the start response into
/v1/zipstateunchanged?