// DOCS · ERROR RESPONSES

When things go wrong.

Every error the entit.ai API returns, in canonical form. Sourced directly from handler_submit.go, handler_poll.go, and the x402 middleware.

POST /v1/jobs

// submit errors

HTTP 400POST /v1/jobs

Empty body / missing url field.

BODY · 400json

{
  "error": "No url provided"
}

HTTP 400POST /v1/jobs

URL is a TikTok photo/slideshow (containing /photo/). Slideshows are not supported.

BODY · 400json

{
  "error": "TikTok slideshow conversion is not supported"
}

HTTP 400POST /v1/jobs

URL did not resolve to a supported platform (tiktok, instagram reels, youtube shorts).

BODY · 400json

{
  "error": "Error resolving url: currently we only support tiktok, instagram and youtube shorts urls"
}

HTTP 400POST /v1/jobs

Could not extract a stable videoId from the resolved URL.

BODY · 400json

{
  "error": "Error getting video ID"
}

HTTP 400POST /v1/jobs

format was set but is not one of the closed enum of workflow slugs. The full list lives at /docs/api#workflow-formats and in /llms.txt. Submitted value is echoed in the error message for debugging.

BODY · 400json

{
  "error": "invalid format: must be one of the workflow formats listed at https://entit.ai/docs/api#workflow-formats"
}

HTTP 402POST /v1/jobs

Missing or invalid X-Payment header. Body is an x402 PaymentRequiredResponse describing the accept schemas.

BODY · 402json

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "resource": "POST /v1/jobs",
      "payTo": "0x000000000000000000000000000000000000dEaD",
      "maxAmountRequired": "$0.10",
      "description": "Submit a TikTok, Instagram Reel, or YouTube Shorts URL for transcript + visual analysis. Poll GET /v1/jobs/{jobId} (free) until status is success.",
      "mimeType": "application/json"
    },
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "resource": "POST /v1/jobs",
      "payTo": "11111111111111111111111111111111",
      "maxAmountRequired": "$0.10",
      "description": "Submit a TikTok, Instagram Reel, or YouTube Shorts URL for transcript + visual analysis. Poll GET /v1/jobs/{jobId} (free) until status is success.",
      "mimeType": "application/json"
    }
  ]
}

HTTP 500POST /v1/jobs

Internal failure writing to Firestore or publishing to Pub/Sub. Retry after backoff.

BODY · 500json

{
  "error": "failed to enqueue job"
}

GET /v1/jobs/{jobId}

// poll errors

HTTP 404GET /v1/jobs/{jobId}

Unknown jobId. Job was never created or already pruned.

BODY · 404json

{
  "error": "Job not found"
}

HTTP 410GET /v1/jobs/{jobId}

Job exists but ExpiresAt has passed (24h after submission). The job is gone.

BODY · 410json

{
  "error": "Job expired"
}

HTTP 200GET /v1/jobs/{jobId}

Job finished with status: failed. The error field describes the reason.

BODY · 200json

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "videoId": "7123456789",
  "status": "failed",
  "error": "video download timed out"
}

HTTP 500GET /v1/jobs/{jobId}

Internal failure reading or parsing the job document.

BODY · 500json

{
  "error": "failed to get job"
}

// RETRY GUIDANCE

4xx: do not retry blindly — fix the request first.
402: re-issue with a valid x402 X-Payment header constructed from the accept schema.
5xx: exponential backoff. Server-side issues are usually transient Firestore or Pub/Sub blips.
While pending/processing the server emits Retry-After: 5 — honor it.

See also: API reference · VideoAnalysis schema.