Error Handling

AntCDN APIs use standard HTTP status codes and return structured error bodies for validation and runtime failures.

What to Check First

• Status code: 4xx means the request needs changing; 5xx means retry/backoff.
• Request IDs / logs: If you have server logs, log the status + response body.
• Clock drift: For signed URLs, make sure your system clock is reasonably correct.

Common Status Codes

Retry Strategy

• Safe to retry: Most GETs, and idempotent operations.
• Use exponential backoff: e.g. 250ms → 500ms → 1s → 2s (cap at ~10s).
• Don’t retry forever: Use a max attempts/time budget.

Upload-Specific Errors

POST /videos/upload-url succeeds but the upload fails

• Network failures, 408, 429 or 5xx on resumableUploadURL: Ask how many bytes are stored and continue from there. Nothing already uploaded is lost. See Uploading With a Pre-Signed URL.
• 404 or 410 on resumableUploadURL: The session expired one week after it was created. Request new upload URLs and upload again.
• 403 on signedURL: The Content-Type header is missing or differs from contentType in the upload-url response, or the URL is more than a week old.
• Network failures on signedURL: The PUT must restart from byte 0. Use resumableUploadURL for large files instead.

Processing takes a while

Processing time depends on file size, source codec complexity, and quality settings. Poll video details and wait for status.ready.

Example: Robust Fetch Wrapper (JavaScript)

async function antcdnFetch(url, init) {
  const res = await fetch(url, init);
  const text = await res.text();
  let payload;
  try {
    payload = text ? JSON.parse(text) : null;
  } catch {
    payload = text;
  }

  if (!res.ok) {
    const detail =
      payload && typeof payload === "object" && "detail" in payload ? payload.detail : undefined;
    const msg = detail ? String(detail) : `Request failed: ${res.status}`;
    const err = new Error(msg);
    err.status = res.status;
    err.payload = payload;
    throw err;
  }

  return payload;
}