Paybond errors should be handled as part of the product flow, not just as generic transport failures. Some failures mean "retry later," while others mean "the request is not allowed" or "the current business state does not permit this action."
Retry model
- Treat most 4xx responses as final until the caller or business state changes.
- Retry 5xx, network failures, and 429 responses with exponential backoff and jitter.
- Reuse the same idempotency key when retrying the same write request.
- Treat capability denies and predicate failures as expected workflow outcomes, not infrastructure failures.
What to log
- HTTP status code
- Request URL (without credentials)
- Response body after redacting sensitive fields
- Correlation identifiers such as
request_idwhen present tenant_idandintent_idwhen they are relevant to the request
What not to log
- API keys
- Harbor or Gateway bearer tokens
- Capability tokens
- Raw signing seeds or any other secret material
Safe retries
If you retry evidence submission, intent creation, or another supported write operation, reuse the same idempotency key for the same request. Do not reuse an idempotency key across distinct payloads.