Errors and Retries

Handle failures at three levels: the HTTP request, the batch or job, and the individual valuation row.

HTTP Status Codes

Validation Errors

Validation failures return stable error codes together with server-generated identifiers:

{
  "api_version": "v3",
  "execution_id": "<server-generated-uuid>",
  "valuation_id": "<server-generated-uuid>",
  "request_reference": "valuation-001",
  "status": "rejected",
  "errors": [
    {
      "code": "property_type_subtype_mismatch",
      "field": "property",
      "message": "subtype flat requires property type F",
      "retryable": false
    }
  ]
}

Correct the request or source data before retrying.

Transport and admission errors can instead use a detail string or an object such as {"detail":{"code":"serving_capacity_exhausted"}}. Do not assume every unsuccessful HTTP response contains a valuation envelope or errors[].

Job Availability

asynchronous_valuation_job_admission_closed or valuation_job_worker_not_ready means new jobs cannot currently be accepted. Wait before retrying, and retain the same idempotency key and body. Existing job status and completed results can still be retrieved during an admission pause. Do not treat a documented job endpoint as a guarantee of immediate availability.

Identity Errors

Stable codes include:

property_identity_incomplete
address_not_found
address_match_not_exact
uprn_address_mismatch
unsupported_geography
identity_provider_not_configured
identity_provider_configuration_error
identity_provider_unavailable
identity_provider_rejected_request
identity_provider_invalid_response

Each identity error includes retryable:

• false: correct the address and UPRN pair or route the request for manual handling;
• true: retry with bounded exponential backoff.

Ambiguity is not transient. Never repeatedly send the same fuzzy address.

Manual Valuation Referral

Representative response:

{
  "api_version": "v3",
  "execution_id": "<server-generated-uuid>",
  "valuation_id": "<server-generated-uuid>",
  "request_reference": "valuation-001",
  "status": "referred",
  "manual_review": {
    "code": "manual_valuation_required",
    "reasons": [{"code": "large_or_nonstandard_land"}]
  },
  "input_resolution": {
    "stored_data_used": [],
    "ignored_inputs": [],
    "derived_inputs": []
  }
}

Common reason codes include:

missing_floor_area
floor_area_outside_market_domain
room_density_outside_market_domain
room_count_inconsistent_with_floor_area
large_or_nonstandard_land
insufficient_independent_evidence
very_low_market_liquidity
market_eligibility_unavailable

Display “automated valuation unavailable; manual review required” rather than “property cannot be valued”. A referral is an expected response, not a system failure. Do not retry the same request without changes.

Batch Row Errors

Valid row statuses:

A batch may return HTTP 200 with status=partial. Always inspect the status of every row.

Job Errors

Stable job codes include:

valuation_jobs_not_configured
valuation_job_conflict
idempotency_key_reused_with_different_input
valuation_job_submission_failed
valuation_job_metadata_unavailable
valuation_job_not_found
valuation_job_result_unavailable
valuation_job_idempotency_key_expired

Use the same idempotency key and identical body when retrying an uncertain job submission. Reusing a key with a different body is a client error. An expired idempotency key returns 409; use a new key for new work rather than treating expiry as a transient failure.

Access and Plan Errors

invalid_api_key
insufficient_scope
request_body_too_large
plan_batch_limit_exceeded
monthly_valuation_quota_exceeded
tenant_concurrency_limit_exceeded
admission_control_unavailable
engine_not_initialized

A depleted monthly quota cannot be resolved by retrying. Concurrency limits, by contrast, may be temporary; follow the returned retry guidance.

Processing and Payload Controls

Standard and development synchronous requests may return:

serving_capacity_exhausted
serving_profile_not_ready
request_body_timeout
compressed_request_body_not_supported
valuation_deadline_exceeded

Temporary capacity responses include Retry-After. A deadline response is not an instruction to immediately resubmit: the original work may still be finishing. See Limits and Safeguards.

Retry Strategy

Retry only retryable 429, 500 and 503 outcomes. Use full jitter:

delay = random(0, min(cap, base * 2^attempt))

Recommended baseline:

• base: 0.5 seconds;
• cap: 20 seconds for interactive calls, 60 seconds for backend jobs;
• maximum attempts: 4 interactive, 6 background;
• always honour a larger server Retry-After;
• use the same request_reference and job idempotency key.

request_reference is a label, not an idempotency control. Repeating a synchronous request can perform and charge for another valuation, even with the same reference. Job idempotency applies only when the same job key and request body are reused.

Do not retry 400, 401, 403, permanent 404, 409, 413, non-retryable 422, or permanent identity failures. Never automatically retry monthly_valuation_quota_exceeded, even if the response includes Retry-After.

Timeouts

Set separate connection and response timeouts. A client timeout does not confirm whether the service accepted the request. For synchronous calls, reconcile the outcome against your request records before repeating a large batch. For jobs, resubmit the identical request with the same idempotency key.

Support Information

For investigation, retain:

• X-Valtaic-Request-Id response header;
• X-Valtaic-Execution-Id, execution_id, and valuation_id;
• customer request_reference;
• release_id;
• endpoint and HTTP status;
• complete public error body;
• timestamp and environment;
• job ID and idempotency key where applicable.

Never send your API key in a support ticket.