Integration diagnostics
Use request IDs, stable claim IDs, and decision details to distinguish policy behavior from transport failures.
Shared proxy IP
If unrelated customers all use one IP in your requests, check your proxy configuration. Resolve the original IP only from headers set by infrastructure you trust. Do not pass your application server’s IP.
Reused recipient or claim IDs
An external ID represents the benefit recipient. Reusing it across customers joins their matching history. A claim ID represents one logical award. Reusing a claim for different recipients returns CLAIM_CONFLICT.
Idempotency conflict
Reuse a key only with its original payload. After correcting inputs or changing a policy for a denied claim, keep the claim ID and use a new attempt key.
Unresolved confirmations
Compare Veltor’s grant state with your customer-side ledger. Report granted only when delivery is known; report not_granted only when failure is known. A timeout alone is not evidence of failed delivery.
Unavailable dependencies
Redis unavailability returns a bounded 503; traffic limits return 429 with Retry-After. Database and lock failures remain technical errors. Retry within your chosen budget, then apply your explicit local outage behavior.