Error Handling

Goal

Build safe fallback behavior for scan errors.

Pause high-risk workflows for review. Low-risk workflows can retry or use a limited fallback.

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 === 415) return "fix_request";
  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 steg, ai, edits, all, metadata, and supported two-path combinations. Deprecated aliases are accepted only for compatibility. Structured documents accept routing focus values, but image/PDF visual evidence does not apply.
• focus=metadata with text or a structured document returns metadata_unsupported_modality. This focus requires an original JPEG, PNG, WebP, GIF, classic TIFF, HEIF, or PDF in mode=secure.
• Base64 missing when JSON contains non-text content.
• Multipart request without file or content.

Billing And PDF Limit Errors

Routing PDFs have two billing dimensions:

• Page count.
• Unique embedded image count.

For routing PDF scans, billing is additive. Pages cost 2 SCU each. Unique embedded images use the selected focus price:

Focused PDF SCU = pages * 2 + unique embedded images * 4
All-evidence PDF SCU = pages * 2 + unique embedded images * 12
Metadata PDF SCU = analyzed parent * 2 + distinct analyzed native PDF images * 2

focus=metadata has no PDF page charge. Only native images that the metadata scan analyzed count toward its image charge. It runs synchronously in mode=secure and returns NO_DECISION; see the metadata response contract.

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 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 or 415 until the request or file 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.