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_7d18b9a1... is not approved.",
    "requestId": "req_01HXZ9G7KMV2QX8Y1S5RJW3B7T",
    "details": {
      "containerId": "cnt_7d18b9a1-8b2c-4f3e-a4d5-6e7f8a9b0c1d",
      "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 exceeds the max 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

Async jobs 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" }
  }
}

Jobs use the same error vocabulary. The extra field is data.stage: the job stage active when the failure occurred.

One additional code is specific to the job path: WORKFLOW_START_FAILED (500). The request was accepted, but the job could not start. Retry with the same Idempotency-Key.

Retry guidance

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

• RATE_LIMITED - honor Retry-After. Don't add jitter; the server already staggered your bucket reset.
• INTERNAL - exponential backoff with a small attempt cap.
• 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