Errors - CaptionCraft API

Request errors

An unsuccessful API request returns an appropriate HTTP status and a JSON error object:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient available seconds for max_duration_seconds. Lower the limit or add credits.",
    "request_id": "<REQUEST_ID>"
  }
}

Record error.request_id or the X-Request-Id response header when reporting a problem. Do not include your API key in logs or support messages.

HTTP	Code	Action
400	`INVALID_REQUEST`	Correct invalid or unknown JSON fields.
400	`INVALID_JSON`	Send valid JSON.
400	`INVALID_IDEMPOTENCY_KEY`	Use 8–128 permitted characters.
401	`UNAUTHORIZED`	Check the Bearer key and whether it expired or was revoked.
402	`INSUFFICIENT_CREDITS`	Add credit or choose a duration limit that fits the video and balance.
403	`FORBIDDEN`	Check key scopes and account access.
404	`NOT_FOUND`	Check the endpoint, job ID, and account that owns the job.
409	`IDEMPOTENCY_CONFLICT`	Use the original input, or a new key for a deliberately new job.
413	`PAYLOAD_TOO_LARGE`	Keep the request’s JSON body within 16 KiB.
415	`INVALID_CONTENT_TYPE`	Set `Content-Type: application/json`.
429	`RATE_LIMITED`	Wait for `Retry-After` before retrying.
429	`CONCURRENCY_LIMIT`	Wait for capacity on the account.
500	`INTERNAL_ERROR`	Retry with backoff; preserve submission idempotency.
503	`SERVICE_UNAVAILABLE`	Processing is not configured; contact the operator.

Processing errors

A job may be accepted and later fail. Get job still returns HTTP 200; inspect status and error:

{
  "status": "failed",
  "error": {
    "code": "UNSUPPORTED_VIDEO",
    "message": "Unsupported video, missing audio, or exceeded duration/resolution limits."
  },
  "usage": { "reserved_seconds": 0, "billed_seconds": 0 }
}

This is an excerpt of a job response. Common processing codes include:

Code	Meaning
`INVALID_SOURCE`	The source could not be downloaded safely. Check URL expiry, redirects, permissions, and file size.
`UNSUPPORTED_VIDEO`	The video is unsupported, lacks audio, or exceeds the duration or resolution limit.
`NO_SPEECH`	No speech was detected.
`TRANSCRIPTION_FAILED`	Transcription did not complete.
`RENDER_FAILED`	Rendering or output preparation did not complete.
`QUEUE_TIMEOUT`	Processing capacity was not available before the queue deadline.
`WORKER_TIMEOUT`	Processing timed out.
`ACCOUNT_DISABLED`	Account access was disabled before processing.

Failed jobs release reserved credits. Fix the underlying issue, then submit with a new idempotency key if you want another attempt. A replay with the old key returns the existing failed job.