API reference
Errors and limits
Etchv watermarking API errors and limits: HTTP status codes, rate limits, image upload limits, how credits work when you retry, and service status.
Use the HTTP status and the JSON detail field to handle a failure. Save the X-Request-ID header when you report a problem.
Status codes
| Status | What to do |
|---|---|
401 · Authentication | Check the API key |
402 · Billing | Check the plan, credit balance and pending reservations |
403 · Access | Check scopes, membership, formats and GPU eligibility |
404 · Not found | Check the ID in the request (asset, job, webhook or destination) and the Organization |
409 · Conflict | Check idempotency inputs or reload a stale asset version |
410 · Unavailable result | Check the asset library; the file may be expired or deleted |
413 · Too large | Reduce file size, dimensions or frame count |
415 · Unsupported format | Convert to a supported format |
422 · Invalid input or verification failure | Check encoding and JSON; try a different source if verification failed |
429 · Limit reached | Wait for Retry-After seconds, then retry |
503 · Service unavailable | Check service status and retry appropriately |
401· Authentication- What to do
- Check the API key
402· Billing- What to do
- Check the plan, credit balance and pending reservations
403· Access- What to do
- Check scopes, membership, formats and GPU eligibility
404· Not found- What to do
- Check the ID in the request (asset, job, webhook or destination) and the Organization
409· Conflict- What to do
- Check idempotency inputs or reload a stale asset version
410· Unavailable result- What to do
- Check the asset library; the file may be expired or deleted
413· Too large- What to do
- Reduce file size, dimensions or frame count
415· Unsupported format- What to do
- Convert to a supported format
422· Invalid input or verification failure- What to do
- Check encoding and JSON; try a different source if verification failed
429· Limit reached- What to do
- Wait for
Retry-Afterseconds, then retry
503· Service unavailable- What to do
- Check service status and retry appropriately
Rate limits
Limits apply to all your Organization’s keys and dashboard use combined. See allowances by plan.
| Limit | What counts |
|---|---|
| Requests per minute | Every authenticated request, including polling, downloads and refused requests; resets each minute |
| Concurrent operations | Queued or running embedding and async detection jobs, plus durable video detection |
- Requests per minute
- What counts
- Every authenticated request, including polling, downloads and refused requests; resets each minute
- Concurrent operations
- What counts
- Queued or running embedding and async detection jobs, plus durable video detection
Synchronous image and PDF detection count only toward requests per minute. Replaying an existing job does not use another concurrent slot. Batch files are never refused for concurrency; they wait their turn, and each batch poll is one request.
A 429 response reserves no credits. Its detail includes code (rate_limited or concurrency_limited) and limit. Concurrency errors also include upgrade_url.
| Header | Meaning |
|---|---|
Retry-After | Seconds to wait |
X-RateLimit-Limit | Requests allowed this minute |
X-RateLimit-Remaining | Requests left this minute |
X-RateLimit-Reset | Minute reset time, as Unix seconds |
Retry-After- Meaning
- Seconds to wait
X-RateLimit-Limit- Meaning
- Requests allowed this minute
X-RateLimit-Remaining- Meaning
- Requests left this minute
X-RateLimit-Reset- Meaning
- Minute reset time, as Unix seconds
When you poll (check a job’s status again and again), wait at least the job’s Retry-After: 6 seconds on Trial and Launch, 2 on other plans. Webhooks let you skip polling. SDKs retry 429 for embedding, video detection and polling until the client timeout. Other calls return the error.
Image limits
| Limit | Maximum |
|---|---|
| Embedding upload | 50 MB via API or dashboard |
| Delivered file | 192 MB; lossless output can be larger than the upload |
| Detection upload | 95 MB in one request; 192 MB through a large-file upload |
| Frames or pages | 32, including an APNG poster image |
| Total pixels | 40 megapixels across frames or pages |
| GIF frame | 1 megapixel |
| PSD/PSB canvas | 4 megapixels |
| PSD/PSB layers | 64 layers and 16 megapixels total, including two watermark layers |
- Embedding upload
- Maximum
- 50 MB via API or dashboard
- Delivered file
- Maximum
- 192 MB; lossless output can be larger than the upload
- Detection upload
- Maximum
- 95 MB in one request; 192 MB through a large-file upload
- Frames or pages
- Maximum
- 32, including an APNG poster image
- Total pixels
- Maximum
- 40 megapixels across frames or pages
- GIF frame
- Maximum
- 1 megapixel
- PSD/PSB canvas
- Maximum
- 4 megapixels
- PSD/PSB layers
- Maximum
- 64 layers and 16 megapixels total, including two watermark layers
Send the encoded file bytes and a JSON data object that is not empty. URLs and base64 strings are not file uploads. High-bit-depth and CMYK images are not supported. HEIC, HEIF and AVIF return 415. Convert them to JPEG, PNG or WebP first.
Batch limits
| Limit | Maximum |
|---|---|
| Items per batch | 100 |
| Zip request | 55 MB, sent to /watermarks |
| Batch archive | 1 GB of results; larger batches deliver each result_url only |
- Items per batch
- Maximum
- 100
- Zip request
- Maximum
- 55 MB, sent to
/watermarks/batches /zip
- Batch archive
- Maximum
- 1 GB of results; larger batches deliver each
result_urlonly
Each file in a batch also meets the limits of a single request. All batch limits.
Batch item errors
A batch item that is rejected was refused before processing and is never charged. Its error_code says why; error_detail often adds the reason. An item that failed during processing has the same error_code a single job would, and its credits are refunded.
| Code | Meaning | What to do |
|---|---|---|
upload_not_received | The file was not uploaded before the batch started | Send it in a new batch |
upload_size_mismatch | The uploaded file’s size differs from the declared size | Declare the exact size in bytes |
upload_expired | The upload expired before the file was checked | Send it in a new batch |
upload_rejected | The uploaded file was already refused | Fix the file and send it in a new batch |
invalid_input | The file failed the checks a single request makes, such as format, size, pages or frames | Fix the file using error_detail |
refused | Your plan or settings refused the file, such as a format your plan does not include | Check error_detail |
insufficient_credits | Credits ran out; this item and every later one are rejected | Add credits, then send the rejected files again |
cancelled | The batch was canceled before this file ran | Send it in a new batch if you still need it |
admission_failed | Etchv could not check the file after repeated attempts | Send it in a new batch |
upload_not_received- Meaning
- The file was not uploaded before the batch started
- What to do
- Send it in a new batch
upload_size_mismatch- Meaning
- The uploaded file’s size differs from the declared
size - What to do
- Declare the exact size in bytes
upload_expired- Meaning
- The upload expired before the file was checked
- What to do
- Send it in a new batch
upload_rejected- Meaning
- The uploaded file was already refused
- What to do
- Fix the file and send it in a new batch
invalid_input- Meaning
- The file failed the checks a single request makes, such as format, size, pages or frames
- What to do
- Fix the file using
error_detail
refused- Meaning
- Your plan or settings refused the file, such as a format your plan does not include
- What to do
- Check
error_detail
insufficient_credits- Meaning
- Credits ran out; this item and every later one are rejected
- What to do
- Add credits, then send the rejected files again
cancelled- Meaning
- The batch was canceled before this file ran
- What to do
- Send it in a new batch if you still need it
admission_failed- Meaning
- Etchv could not check the file after repeated attempts
- What to do
- Send it in a new batch
An upload created for a batch works only in that batch. Using its upload_id in another request returns 409 with upload_in_batch.
Credits and retries
Embedding reserves credits when Etchv accepts the request. It charges them when the checked output is saved, and releases them if the job fails for good. Downloads and replays add no charge. During an outage, reserved credits stay pending until a worker finishes or closes out the job.
| Situation | Action |
|---|---|
| Client timeout | Resume with the request ID, or resend the same inputs and idempotency key; the accepted job continues |
Final status: "failed" | Inspect error_code; the same key returns the same failure |
| Sync image/PDF detection error | Handle in your code; SDKs do not retry these calls automatically |
| Upload to your own storage fails | Inspect delivery errors; the checked output is still valid and retries add no charge |
- Client timeout
- Action
- Resume with the request ID, or resend the same inputs and idempotency key; the accepted job continues
- Final
status: "failed" - Action
- Inspect
error_code; the same key returns the same failure
- Sync image/PDF detection error
- Action
- Handle in your code; SDKs do not retry these calls automatically
- Upload to your own storage fails
- Action
- Inspect delivery errors; the checked output is still valid and retries add no charge
See retry rules and credit costs.
Service status
Check status.etchv.com. For help, send hello@etchv.com the request ID and HTTP status. Never send your API key.