Errors

Network reference: For the full cross-tool error code reference, see tools.fast/api/docs/errors.

Error envelope

All API errors return a JSON object with at least two fields:

{
  "error": "machine.readable_code",
  "detail": "Human-readable explanation."
}

Some errors include additional context fields. URL fetch errors include an isRetryable boolean indicating whether the request can be retried (e.g. transient network failures vs permanent validation errors).

400 Bad Request

Invalid request payload, parameters, or content type.

{
  "error": "request.invalid_content_type",
  "detail": "multipart/form-data or application/json required."
}

{
  "error": "request.empty_file",
  "detail": "Uploaded file is empty."
}

{
  "error": "request.no_files",
  "detail": "Exactly one file must be provided."
}

{
  "error": "request.invalid_extension",
  "detail": "File extension '.mp3' is not accepted by this compressor."
}

URL fetch errors (400)

Returned when URL-based input (inputUrl) fails validation or the remote server returns an error.

{
  "error": "url_fetch.invalid_url",
  "detail": "inputUrl is required in JSON body.",
  "isRetryable": false
}

{
  "error": "url_fetch.invalid_scheme",
  "detail": "Only HTTPS URLs are allowed.",
  "isRetryable": false
}

{
  "error": "url_fetch.private_ip",
  "detail": "URL resolved to blocked IP address (private/reserved).",
  "isRetryable": false
}

{
  "error": "url_fetch.mutually_exclusive",
  "detail": "Cannot provide both a file upload and inputUrl. Use one or the other.",
  "isRetryable": false
}

{
  "error": "url_fetch.output_url_reserved",
  "detail": "outputUrl is reserved for future use and not yet supported.",
  "isRetryable": false
}

{
  "error": "url_fetch.http_error",
  "detail": "Remote server returned 503 Service Unavailable.",
  "isRetryable": true
}

401 Unauthorized

The API key is missing, invalid, or not allowed from the caller's IP.

{
  "error": "api_key.invalid_or_ip_not_allowed",
  "detail": "X-Fast-Api-Key was provided but is invalid for this request (or IP not allowlisted)."
}

This error intentionally does not distinguish between an invalid key and an IP not in the allowlist.

402 Payment Required

The caller's account does not have enough credits.

{
  "error": "entitlements.insufficient_credits",
  "detail": "Insufficient credits. Required: 5, Available: 2"
}

403 Forbidden

The resource exists but the caller does not own it, or the action is not allowed for the caller's account.

{
  "error": "jobs.forbidden",
  "detail": "You do not have access to this job."
}

{
  "error": "url_fetch.guest_not_allowed",
  "detail": "URL-based input is not available for guest users. Please sign in.",
  "isRetryable": false
}

404 Not Found

The requested job does not exist.

{
  "error": "jobs.not_found",
  "detail": null
}

409 Conflict

The request conflicts with the current state of the resource.

{
  "error": "jobs.not_ready",
  "detail": "Job is still processing or waiting to start."
}

{
  "error": "jobs.not_cancellable",
  "detail": "Cannot cancel completed, failed, or canceled jobs."
}

{
  "error": "jobs.not_deletable",
  "detail": "Cannot delete a job that is still queued or running. Cancel it first."
}

410 Gone

The job completed but its output artifacts have expired and been cleaned up. Output artifacts are retained for 1 hour after job completion, then automatically deleted. To clean up immediately after downloading, call DELETE /compress/job/{id}.

{
  "error": "jobs.expired",
  "detail": "Job artifacts were deleted on 2025-01-15 12:00:00Z after the retention period expired."
}

413 Payload Too Large

The uploaded file exceeds the per-compressor or global size limit.

{
  "error": "request.file_too_large",
  "detail": "File exceeds the maximum allowed size.",
  "megabytes": 50
}

429 Too Many Requests

The caller has been throttled. Check the Retry-After header.

{
  "error": "rate_limited",
  "detail": "Too many requests. Retry after 12 seconds."
}

{
  "error": "queue.limit_exceeded",
  "detail": "Too many queued jobs. Wait for existing jobs to complete."
}

{
  "error": "url_fetch.rate_limited",
  "detail": "Too many concurrent URL fetches. Please wait and retry.",
  "isRetryable": true
}

Headers on 429 responses:

Best practice: implement exponential backoff in your client, or honour the Retry-After value directly.

5xx Server Error

Server-side errors are rare but possible. Retry with exponential backoff (1s, 2s, 4s, 8s, max 30s). If errors persist, contact support@tools.fast.

Error codes reference