Error Handling

Goal

Build safe fallback behavior for scan errors.

High-risk workflows should fail to review. Low-risk workflows can retry or degrade with clear limits.

Error Shape

Errors may include an error message, code, request ID, and scan group ID.

{
  "error": "scan_phase must be 'input' or 'output'",
  "code": "invalid_scan_phase",
  "request_id": "ab82f4ad-8d64-4bb4-b4ed-77df63291198",
  "scan_group_id": "9b3e4f8d-96c9-4f42-8338-8cf9571c1c70"
}

Status Codes

Safe Fallback Policy

export function fallbackForScanError(status: number, workflowRisk: "low" | "high") {
  if (status === 400) return "fix_request";
  if (status === 402) return "billing_or_tier_action";
  if (status === 413) return "reduce_or_review";
  if (status === 429) return "retry_with_backoff";

  return workflowRisk === "high" ? "manual_review" : "retry_then_degrade";
}

Common 400 Causes

• Missing scan_phase.
• scan_phase=output without scan_group_id.
• Invalid UUID in request_id or scan_group_id.
• content_type outside auto, text, image, pdf, or document.
• Invalid focus outside the canonical steg, ai, edits, all, and supported combination values (deprecated aliases are accepted only for compatibility). Structured documents accept canonical focus values and report non-applicable visual surfaces in document_integrity.unsupported_surfaces.
• Base64 missing when JSON contains non-text content.
• Multipart request without file or content.

Billing And PDF Limit Errors

PDFs have two separate dimensions:

• Page count.
• Unique embedded image count.

Billing is additive. Pages stay 2 SCU each. Unique embedded images use the active focus image-unit price:

Focused PDF SCU = pages * 2 + unique embedded images * 4
All-evidence PDF SCU = pages * 2 + unique embedded images * 12

Tier caps are separate from SCU. A scan can be blocked before billing if the PDF exceeds the tier's page or embedded image limit.

Async States

Retry Rules

• Honor Retry-After on 202 polling and 429 capacity responses; add bounded backoff and jitter.
• Retry 503 idempotently only when your workflow can confirm it did not already receive a 202 for that scan.
• Retry network errors with a unique request_id unless your app already committed the prior request.
• Do not retry 400 until the request is fixed.
• Do not hide 402 or 413. Those need product routing.
• Keep webhook processing idempotent.

AI-Agent Prompt

Add Citadel error handling.

Requirements:
- Parse non-2xx responses.
- Handle 400 as a developer or request shape error.
- Handle 402 as billing, quota, or tier cap.
- Handle 409 as idempotency conflict.
- Handle 413 as file size, PDF page cap, embedded image cap, or payload complexity.
- Handle 429 with backoff.
- Treat async pending as pending, not as final.
- Treat async failed as manual review for high-risk workflows.
- Include request_id and scan_id in logs when available.

Acceptance criteria:
- Tests cover 400, 402, 409, 413, 429, network error, pending, complete, and failed.
- High-risk workflows never continue silently after a scan failure.