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 PUT signedURL fails

• 403/Signature error: The pre-signed URL expired; request a new one.
• 415/Content-Type mismatch: If you’re setting Content-Type, set it consistently.
• Network failures: Retry the PUT (and if you restart after a long delay, request a fresh signed URL).

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;
}