← All articles

INTEGRATIONS / ARCHITECTURE

A reliable integration error-handling pattern

A successful HTTP request is not the same thing as a successful business operation. An API can return an HTTP 200 response whose body reports that the requested operation failed.

Classify failures clearly

  • Transport: connectivity, timeouts, TLS, unavailable host.
  • Authentication/authorization: invalid credentials or insufficient permissions.
  • Validation: malformed input, missing data, unsupported state.
  • Business outcome: the external system accepted the request but could not complete the operation.
  • Unexpected response: parsing failures or undocumented schemas.

Use a stable internal result shape

{
  "success": false,
  "category": "VALIDATION",
  "httpStatus": 422,
  "message": "One or more fields are invalid",
  "correlationId": "example-123"
}

Build a small transformation layer that normalizes downstream responses to a consistent internal contract. Keep diagnostic details available for authorized troubleshooting, but avoid displaying sensitive data to end users.

Practical design

Store a correlation ID, request type, timestamp, technical outcome and safe error category. Use retry policies only for operations where retry is justified and idempotency is understood.

Takeaway

Separate what failed, why it failed, and what the application should do next. This makes integrations easier to debug and safer to recover.