Error handling

Principles

Treat 4xx errors as non-retriable unless explicitly documented as safe to retry.
Treat 5xx and network failures as retriable, using exponential backoff and jitter.
Use idempotency keys on mutating operations that may be retried.
Log enough structured context to debug tenant-scoped issues without logging secrets.

What to log

HTTP status code
Request URL (without credentials)
Response body (redact sensitive fields)
Correlation identifiers returned by the service (if present)
tenant_id (the realm from Gateway harbor-access) and intent_id when applicable

Safe retries

If you retry evidence submission or settlement confirmation, use the same idempotency-key for the same request fingerprint. Do not reuse an idempotency key across distinct payloads.