Errors

All error responses use a consistent envelope:

{
  "error": {
    "code": "validation_error",
    "message": "Human-readable explanation.",
    "request_id": "req_01J…",
    "details": []
  }
}

request_id is safe to send to Appraiser Flow support.

HTTP status map

Status	When
400	Malformed JSON / bad headers
401	Missing, invalid, revoked, or wrong-environment API key
403	Scope missing or IP not on allowlist
404	Resource not found in this tenant (also used for cross-tenant ids)
409	Idempotency key reused with a different body
422	Semantically invalid (incomplete address, inactive product)
429	Rate limited — respect Retry-After if present
500/503	Unexpected / temporary — retry with backoff

Notable error.code values

code	Meaning
invalid_api_key	Bad or revoked bearer
insufficient_scope	Key lacks required scope
ip_not_allowed	Caller IP not on key allowlist
rate_limited	Too many requests
validation_error	Schema/field validation failed
coverage_unavailable	Firm does not cover area/product
product_inactive	Product code not offered
address_incomplete	Subject address missing required parts
idempotency_conflict	Same key, different payload
unsupported_content_type	Upload type not allowed
not_found	Unknown id for this tenant

Retry guidance

Situation	Retry?
429, 503	Yes — exponential backoff + jitter
409 idempotency_conflict	No — fix payload or use a new Idempotency-Key
401/403	No — fix credentials/scopes
422	No — fix request body
Network timeout on POST create	Yes — same Idempotency-Key