Back to Documentation

Errors and Partial Failures

Guidance for interpreting errors[] and partial results.

Error model

Verifact uses HTTP status codes for transport/auth/validation failures and a structured errors array for domain or processing issues. Some processing problems are surfaced on an HTTP 200 response with entries in errors[].

Clients must check both the HTTP status and payload fields (for example errors[], verdict or status) before trusting results.

Example error codes

Common example codes (placeholders):

  • timeout
  • fetch_failed
  • source_not_found

What to do

Retryable vs non-retryable: Treat transient issues (for example network timeouts, service_unavailable) as retryable with exponential backoff. Treat validation and clearly permanent errors (for example malformed requests or missing configuration) as non-retryable and surface them to operators.

Surfacing needs_review: If a result or requirements decision indicates needs_review or the errors array contains ambiguous failures, route the item to a manual review queue and log the job_id/request_id for traceability.

Always record job_id, request IDs, and any item-level error codes to aid debugging and post‑incident analysis.

See also: Developer Guide · API Reference