Errors and retries

Business and validation errors use this shape:

{
  "message": "Human-readable summary",
  "detail": "Optional diagnostic detail"
}

Authentication, throttling, and idempotency failures can return a detail field without message. Branch on the HTTP status before reading either field.

Status	Meaning	Action
`400`	Business rule failed	Correct the state or input
`401`	Signature failed	Check key, clock, canonical value, and body bytes
`403`	Scope, host, or IP denied	Correct the key policy
`404`	Resource not found for this institution	Check the ID
`409`	Replay, duplicate, or state conflict	Reconcile before retrying
`410`	Quote expired	Create a new quote
`422`	Schema validation failed	Correct the reported field
`429`	Rate limit reached	Back off with jitter
`503`	Pricing or dependency unavailable	Retry with bounded backoff

Safe retries

Store a correlation ID before the first request.
Reuse external_id when reconciling quote creation.
Reuse Idempotency-Key for the same supported write and body.
Generate a new timestamp, nonce, and signature for every HTTP attempt.
After a timeout or server error, read the resource before writing again.

Vantage stores idempotent responses for 48 hours. Reusing a key with a different method, path, or body returns 409 Conflict.

Get started

Build your integration

Safe retries

​Safe retries

Safe retries