Troubleshooting Uploading Images

Use this guide when Imgwire uploads fail, image records stay PENDING, a browser upload is blocked, or your app receives validation, authentication, CORS, or quota errors.

How uploads work

Imgwire standard uploads are a two-step flow:

1. Your app creates an image record with POST /api/v1/images/standard_upload.
2. Your app uploads the image bytes to the returned presigned upload_url.

Do not send image bytes to the Resource API request body. Send metadata to Imgwire first, then PUT the file bytes to the returned upload URL.

curl https://api.imgwire.dev/api/v1/images/standard_upload \
  -X POST \
  -H "Authorization: Bearer $IMGWIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "avatar.png",
    "mime_type": "image/png",
    "content_length": 348221
  }'

Then upload the bytes:

curl "$UPLOAD_URL" \
  -X PUT \
  -H "Content-Type: image/png" \
  --upload-file ./avatar.png

Authentication errors

401 responses usually mean the key, token, or bearer credential is missing, invalid, or not accepted for that operation.

Check these first:

• Use a Server API Key for backend image management, URL uploads, deletes, upload token creation, CORS origins, custom domains, and metrics.
• Use a Client Key only for supported frontend flows such as standard upload creation and image lookup.
• Do not put a Server API Key in browser code, React Native bundles, or public static assets.
• For signed frontend uploads, make sure the frontend sends a valid upload token issued by your backend.
• If you are using a dashboard session or OAuth-linked agent instead of an environment-scoped key, include the target X-Environment-Id header where required.

Browser CORS errors

If the request works from a backend or CLI but fails in the browser, check CORS origins.

Imgwire compares the browser Origin header against the Environment's configured CORS origins for Client Key standard upload creation. If the Environment has no CORS origins, any browser origin can attempt upload creation with a valid Client Key. Once you add one or more CORS origins, the browser origin must match one of them.

Common fixes:

• Add your production app host, such as app.example.com.
• Add local development hosts with ports, such as localhost:3000.
• Do not include URL paths in CORS origin patterns.
• Use wildcard patterns such as *.example.com only when multiple subdomains need access.

See CORS Origins for the supported pattern syntax.

File type and size failures

Imgwire accepts these upload MIME types:

image/jpeg
image/jxl
image/png
image/webp
image/avif
image/gif
image/vnd.microsoft.icon
image/heic
image/bmp
image/tiff

Client Keys can restrict uploads further with allowed_mime_types. If a file is valid for Imgwire but not valid for the Client Key, upload creation fails with a validation error.

Also check size limits:

Constraint	Limit
Client Key maximum_upload_bytes	Up to 100 MiB, depending on key configuration
Default Client Key max	50 MiB
Upload by URL max	100 MiB
Decoded image area	250MP
Animated GIF decoded span	Full decoded page span must stay under 250MP

See Imgwire Image Size Limits for details.

Image stays PENDING or PROCESSING

An image record can exist before the uploaded bytes are processed. If the record stays busy:

• Confirm the file bytes were uploaded to the returned upload_url.
• Confirm the Content-Type used for the upload matches the image you declared.
• Retrieve the image record and check status, mime_type, size_bytes, width, height, and processed_metadata_at.
• If you retry upload creation for the same logical file, use idempotency_key so retries do not create duplicate records.
• If the image reaches QUARANTINE, treat it as not ready for delivery and report the image ID if you need help.

Image statuses are PENDING, PROCESSING, READY, and QUARANTINE.

Upload by URL fails

URL uploads use POST /api/v1/images/upload_via_url and require a Server API Key. File name and MIME type are optional overrides; Imgwire can infer them from the source URL and response metadata where possible.

If a URL upload fails:

• Confirm the source URL is reachable by Imgwire, not only by your browser.
• Confirm the source response is an image type Imgwire accepts.
• Confirm the remote file is under 100 MiB.
• Avoid source URLs that expire before Imgwire can fetch them.
• Include purpose and custom_metadata so imported images are easier to identify later.

Common error checklist

Symptom	Likely cause	Fix
401 Invalid API key	Wrong key type, expired key, or missing bearer	Use the correct Client Key or Server API Key
401 Invalid upload token	Signed upload token missing or invalid	Issue a fresh token from your backend
422 file_name must include a file extension	Upload metadata is incomplete	Include a file name such as hero.png
422 mime_type is not allowed	Client Key restricts image MIME types	Update the Client Key or reject that file in your UI
422 content_length exceeds...	File exceeds Client Key maximum_upload_bytes	Lower the file size or adjust the Client Key setting
Browser CORS error	Origin does not match configured CORS origins	Add the browser origin in the Environment
402 PaymentRequiredError	Subscription or quota condition blocks operation	Review billing, storage, upload, or plan status

Related pages

• Frontend Quickstart
• Backend Quickstart
• Images
• CORS Origins
• Supported Image Types
• Image Size Limits

Last updated at: May 8, 2026