Branch on stable codes, not human messages

Error responses use application/problem+json with an HTTP status and a machine-readable code. Map codes into your own typed error model at the data-access boundary. Human-readable details are safe diagnostics and may be localized or clarified later; they should never drive application control flow or be displayed as raw infrastructure exceptions.

Treat 401 as configuration or revocation

An authentication_required response means X-API-Key is missing, malformed or revoked. Automatic retry with the same key cannot fix it and may amplify noise. Stop the operation, alert the integration owner and verify secret deployment. Do not fall back to another customer's key or expose the upstream response to a browser.

HTTP 402 is a budget boundary

insufficient_credits is deterministic and includes cost and remaining balance. Suspend scheduled jobs, preserve interactive read-only UI from cached data where appropriate and send the billing owner to the developer dashboard. A tight retry loop only creates repeated rejected calls and hides the commercial action required.

Retry only bounded, safe operations

Respect Retry-After on 429 and use exponential backoff with jitter for transient 502 provider failures. GET requests and idempotent user provisioning are natural retry candidates. Do not blindly repeat a connection mutation after an unknown response; first list accounts and reconcile whether the resource was created.

Carry correlation IDs across your boundary

Send a validated X-Correlation-ID from your backend and include it in structured logs alongside portfolioId, endpoint operation and latency. This joins product and API diagnostics without recording secrets. Return a safe support reference instead of provider payloads, database details or stack traces.