Platform

Errors

All error responses use a consistent JSON body with human-readable error and machine-readable code fields.

Error format

json

{
  "error": "Too many requests",
  "code": "rate_limit_exceeded"
}

HTTP status catalog

400

Bad Request

validation_error

The request is malformed or fails validation before processing starts.

Common causes

Missing or invalid operation field
No file uploaded or more than one file
Wrong file type for the selected operation
Corrupt file that fails magic-byte checks
Malware scan rejected the upload

Debugging

Inspect the error message in the JSON body
Confirm Content-Type is multipart/form-data for POST /tasks
Verify operation is compress-pdf or image-to-webp
Open the file locally to confirm it is not corrupt

Solutions

Send exactly one file via the file field
Match file MIME/extension to the operation
Keep files under 20 MB
Replace infected or unsupported files

Examplejson

{
  "error": "Field \"operation\" must be one of: compress-pdf, image-to-webp",
  "code": "validation_error"
}

401

Unauthorized

unauthorized

An API key was provided but could not be authenticated.

Common causes

Typo in X-API-Key
Revoked or inactive key
Key belonging to a deactivated user

Debugging

Compare key prefix (first 16 characters) with your dashboard copy
Ensure the header name is exactly X-API-Key
Confirm you are not sending Bearer tokens instead

Solutions

Generate a new live key and rotate secrets
Omit the header to use anonymous limits while testing
Store keys in a secrets manager — never in client-side code

Examplejson

{
  "error": "Invalid API key",
  "code": "unauthorized"
}

403

Forbidden

forbidden

Authentication succeeded or was skipped, but the caller is not allowed to access the resource.

Common causes

Missing or invalid X-Task-Access-Token
Access token for a different taskId
Expired task access token
Anonymous create without a resolvable client IP in production

Debugging

Reuse the exact accessToken from the create response
Confirm the token is sent on status and download calls
Check that the task has not exceeded its 1-hour TTL

Solutions

Persist accessToken with the taskId in your job store
Do not share access tokens across tasks
Use an API key for server-side integrations behind proxies

Examplejson

{
  "error": "Access denied",
  "code": "forbidden"
}

404

Not Found

not_found

The task does not exist, has expired, or the result is not available.

Common causes

Wrong task UUID
Task TTL expired (1 hour)
Download requested before COMPLETED
Result object already cleaned up

Debugging

Call GET /tasks/{id} and inspect status
Confirm the UUID matches the create response
Check expiresAt on the status payload

Solutions

Poll until COMPLETED before downloading
Download promptly after completion
Create a new task if the previous one expired

Examplejson

{
  "error": "Task not found",
  "code": "not_found"
}

409

Conflict

conflict

The request conflicts with the current state of the resource or account limits.

Common causes

Too many concurrent PENDING/PROCESSING tasks for the API key
Idempotency race under extreme concurrency (rare)

Debugging

List in-flight jobs in your own system
Inspect rate-limit and concurrent limit documentation

Solutions

Wait for existing tasks to finish before creating more
Respect the default max of 5 concurrent tasks per key
Use Idempotency-Key for safe retries without duplicates

Examplejson

{
  "error": "Concurrent limit exceeded",
  "code": "conflict"
}

413

Payload Too Large

payload_too_large

The upload exceeds the maximum allowed size (20 MB per file).

Common causes

File larger than 20 MB
Content-Length above the multipart overhead allowance

Debugging

Check file size before upload
Inspect Content-Length if the proxy reports it

Solutions

Compress or split source files client-side
For PDFs, pre-optimize images inside the document
Contact sales for Enterprise size limits

Examplejson

{
  "error": "Request body too large",
  "code": "payload_too_large"
}

415

Unsupported Media Type

unsupported_media_type

The Content-Type or file format is not supported for this endpoint/operation.

Common causes

Sending JSON instead of multipart for create
Uploading DOC/XLS when only PDF/images are supported
Mismatched MIME type vs file contents

Debugging

Verify multipart/form-data on POST /tasks
Confirm file magic bytes match the extension

Solutions

Use supported formats only
Convert files before calling the API

Examplejson

{
  "error": "Unsupported media type",
  "code": "unsupported_media_type"
}

422

Unprocessable Entity

unprocessable_entity

The request syntax is valid, but the file cannot be processed as requested.

Common causes

Password-protected or broken PDF
Image that cannot be decoded
Semantically invalid operation parameters

Debugging

Reproduce with a known-good sample file
Inspect FAILED status errorMessage after create

Solutions

Repair or re-export the source file
Remove PDF encryption before upload
Fall back to an alternate operation when available

Examplejson

{
  "error": "Unable to process uploaded file",
  "code": "unprocessable_entity"
}

429

Too Many Requests

rate_limit_exceeded

You exceeded a rate limit window, daily quota, or burst allowance.

Common causes

Anonymous create limit (20/hour/IP)
API key window limit
Daily create quota exhausted
Aggressive polling without backoff

Debugging

Read Retry-After response header
Inspect X-RateLimit-Remaining and X-RateLimit-Daily-Remaining
Separate create traffic from poll traffic in metrics

Solutions

Back off using Retry-After (exponential with jitter)
Authenticate with an API key for higher limits
Poll every 1–2s with exponential backoff, not busy-loops
Upgrade plan if you consistently hit daily quotas

Examplejson

{
  "error": "Too many requests",
  "code": "rate_limit_exceeded"
}

500

Internal Server Error

internal_error

An unexpected error occurred on the server.

Common causes

Transient infrastructure failure
Unhandled exception in the API layer

Debugging

Retry once with the same Idempotency-Key
Capture response body and request id/timestamp for support

Solutions

Retry with exponential backoff
Check https://dev.flimpa.com/status
Contact support if the issue persists

Examplejson

{
  "error": "Internal server error",
  "code": "internal_error"
}

503

Service Unavailable

service_unavailable

A required dependency is temporarily unavailable.

Common causes

Processing worker offline
Processing queue is full
Object storage unavailable
Malware scanning unavailable

Debugging

Check the status page for incidents
Inspect the error message for which dependency failed
Confirm your retries include jitter

Solutions

Retry later with Idempotency-Key
Buffer jobs in your own queue during incidents
Subscribe to status updates for production systems

Examplejson

{
  "error": "Processing worker offline",
  "code": "service_unavailable"
}