Evidence and idempotency
How Valqio makes runtime decisions explainable and safe to retry.
Evidence is the record that explains a runtime decision. Idempotency is what keeps retries from turning one product attempt into multiple usage charges.
Evidence
Decision evidence should let a teammate answer:
- Who asked to run work?
- Which product action, meter, or limit was checked?
- What quantity was requested?
- Was the decision allowed or denied?
- Which plan, credit, quota, reservation, or usage window mattered?
- Which request ID or idempotency key ties the record back to app logs?
Store the request ID, idempotency key, reason code, and any reservation ID next to your own request log when possible. That makes support and engineering investigations much faster.
Idempotency keys
Use one idempotency key for one product attempt.
Good keys are stable and specific:
generateText:workspace_acme:req_123
renderVideo:job_987:reserve
renderVideo:job_987:commitAvoid keys that change on every retry, such as a new timestamp. Avoid keys that are too broad, such as only the customer ID.
Retry rules
| Situation | Key behavior |
|---|---|
| Same request retries after timeout. | Reuse the same key. |
| User starts a new action. | Use a new key. |
| Reservation succeeds and app work starts. | Keep the reservation ID and commit or release it. |
| Commit fails after local work succeeds. | Retry commit with the same commit key. |
| App work fails before completion. | Release with a stable release key. |
The goal is not just correct billing. The goal is explainable runtime behavior when systems retry, time out, or fail halfway through work.