External providers have their own status codes, error names, message formats and transient conditions. Passing those responses directly to your users couples your application to a vendor's implementation and may disclose sensitive information. A provider adapter should translate remote failures into a small set of application-level outcomes.
Define internal categories
Useful categories include authentication configuration failure, permission denial, invalid request, resource not found, quota exceeded, transient dependency failure, timeout and invalid provider response. Map each provider's documented codes to these categories. Keep business outcomes—such as a card being declined—separate from technical failures such as an unreachable payment gateway.
Preserve diagnostic evidence safely
Log the provider name, operation, HTTP status, correlation ID, elapsed time and a sanitized error code. Avoid storing full request or response bodies by default; they may contain tokens, addresses or payment data. If a body fragment is essential for troubleshooting, redact sensitive fields and apply a short retention policy.
Return a stable public contract
Your API should expose its own error code and a safe message. Do not reveal provider stack traces, internal hostnames, account identifiers or raw exception text. Include a correlation ID so support teams can find the corresponding internal log entry without asking users to share secrets.
Decide retryability explicitly
An internal error category should include whether retry is safe, whether user action is needed and whether the operation's final state is known. “Unknown outcome” is important: a timeout after a payment request is not the same as a confirmed failure. Reconciliation may be safer than another immediate attempt.
Further reading
- RFC 9457: Problem Details for HTTP APIs — https://www.rfc-editor.org/rfc/rfc9457
- OWASP Logging Cheat Sheet — https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html