Skip to main content

Error Handling

Lesson status

This lesson is a focused outline. The model is complete; expand with the linked IBM docs.

When an action fails — a validation error, a backend timeout, a rejected message — processing doesn't just stop silently. DataPower raises an error and, if you've configured one, runs an error rule.

How errors flow​

Building blocks​

  • Error rule — a rule with direction Error. It typically matches on an error code and runs actions to build a sensible client-facing response.
  • Error code / message variables — when something fails, variables such as the error code, sub-code, and message are populated so your error rule can inspect what went wrong (var://service/error-code, var://service/error-subcode, error message variables).
  • dp:reject / session.reject — explicitly fail a transaction from XSLT or GatewayScript, which then drives the error rule.
  • On-Error action — within a rule you can place an action that directs flow to specific handling when a subsequent action errors.

Designing good faults​

  • Don't leak internals. Map raw backend errors and stack traces to clean, generic client messages; log the detail internally instead.
  • Use the right status. Return appropriate HTTP status codes (4xx for client errors, 5xx for gateway/backend) and a consistent error body (JSON or SOAP Fault).
  • Be consistent. A single error-shaping stylesheet/script reused across services keeps fault formats uniform.
  • Log for diagnosis. Emit a correlatable log entry (transaction id) so ops can trace the failure — see Logging & Monitoring.

Outline: topics to expand​

  • Matching specific error codes in error rules.
  • Distinguishing client vs. backend failures and timeouts.
  • Producing SOAP Fault vs. JSON error bodies by service type.
  • Correlating errors with transaction IDs in logs.

Reference​

Knowledge Check

What triggers an error rule to run?

A good practice when returning errors to clients is to…