Errors

Errors are a flat set of stable codes. The string identifies the kind of failure; the HTTP status tells you what class of fix it needs. Pick branches on code, not on the message — messages are for humans.

The envelope

Every 4xx and 5xx response carries the same shape:

{
  "error": {
    "code": "APPROVAL_REQUIRED",
    "message": "Content container cnt_01HXZ9... is not approved.",
    "requestId": "req_01HXZ9G7KMV2QX8Y1S5RJW3B7T",
    "details": {
      "containerId": "cnt_01HXZ9G7KMV2QX8Y1S5RJW3B7T",
      "approvalStatus": "pending"
    }
  }
}

• code is stable. We'll add new codes; we won't rename existing ones.
• message is a human sentence. Log it, don't branch on it.
• requestId appears on every response, error or not. Keep it in your logs.
• details is present when a code carries structured context. Fields documented per code below are the ones we guarantee.

Reading the table

We group by behavior, not by HTTP status:

• Caller bugs — your request is wrong. Fix the request; don't retry.
• Policy gates — we refused on purpose. Change state (approve the container, reconnect the account, ask us for a quota bump), then retry.
• Transient — something slipped. Retry with backoff.
• Upstream — a platform (TikTok, Meta, Apple) rejected us. Read details.platformCode and act on the platform's terms.

The "Retry?" column is advice, not a command. A PLATFORM_ERROR for an expired access token isn't worth retrying until you reconnect; a PLATFORM_ERROR for a flaky upload is.

Caller bugs — fix the request

Policy gates — change state, then retry

Transient — retry with backoff

Upstream — platform rejected us

PLATFORM_ERROR is a single code for every upstream failure. The platform lives in details.platform; the platform's own error code lives in details.platformCode; the raw message is details.platformMessage. The upstream is always exactly one of tiktok, meta, apple, instagram, appstore.

Example:

{
  "error": {
    "code": "PLATFORM_ERROR",
    "message": "TikTok rejected the upload: video too long.",
    "requestId": "req_01HXZ9G7...",
    "details": {
      "platform": "tiktok",
      "platformCode": "video_duration_exceeds_limit",
      "platformMessage": "Video duration 185s exceeds max 180s for this account.",
      "retryAfterMs": null
    }
  }
}

retryAfterMs is populated when the platform hands us a retry window. When it's null, treat the error as non-transient until you've addressed the underlying issue.

Job failures

Jobs (async ops) use the same error shape inside the terminal GET /v1/jobs/:jobId response, with one wire-level difference: the structured-context field is named data (not details) on the nested job error, and there is no requestId on it — the outer HTTP response still carries X-Request-Id.

{
  "status": "failed",
  "finishedAt": "2026-04-18T14:22:10Z",
  "error": {
    "code": "MODERATION_BLOCKED",
    "message": "Generated asset failed safety review.",
    "data": { "stage": "finalizing", "safetyCategory": "violence" }
  }
}

The codes are the same table above — you don't learn a second vocabulary for jobs. The extra field is data.stage: the job stage we were on when it failed.

One additional code is specific to the job path: WORKFLOW_START_FAILED (500) — we accepted the POST and allocated the job row, but the underlying workflow start failed. Retry with the same Idempotency-Key.

Retry guidance

Safe defaults, if you're writing this once and forgetting it:

• RATE_LIMITED — sleep Retry-After seconds exactly. Don't add jitter; the server already staggered your bucket reset.
• INTERNAL — exponential backoff starting at 1s, cap 30s, max 3 attempts.
• PLATFORM_ERROR with retryAfterMs — honor it exactly, then retry once.
• PLATFORM_ERROR without retryAfterMs — don't retry. Surface the error to your caller.
• CIRCUIT_OPEN — wait retryAfterSeconds, then make one request to see if the breaker closed. If it's still open, wait again.
• Everything else in the "Caller bugs" and "Policy gates" tables — don't retry until you've fixed state.

Every retry you do should reuse the original Idempotency-Key. That's the whole point of idempotency — cached responses replay, the underlying work doesn't run twice. See Idempotency.

See also

• Rate limits
• Idempotency
• Jobs