Error Handling & Debugging

Robust error handling is critical for building reliable integrations with the MIDSuite Client API. This section explains how errors are communicated and how to diagnose issues when requests fail.

HTTP Status Codes vs API-Level Errors

The MIDSuite API communicates errors using two layers:

HTTP Status Codes

HTTP status codes indicate whether the API endpoint successfully processed the request at a transport level.

Typical responses include:

Even when the HTTP status is 200, the request may still contain API-level errors.

API-Level Success Indicator

All primary responses include the isSuccess flag:

{
  "isSuccess": false,
  "errors": {
    "message": "Validation failed"
  }
}

Important:Applications should always check isSuccess rather than relying solely on HTTP status codes.

Errors Object Structure

When a request fails or contains validation problems, the response includes an errors object.

Example:

{
  "isSuccess": false,
  "errors": {
    "message": "Request validation failed",
    "fieldErrors": {
      "cardNumber": ["Card number must contain 13–19 digits"],
      "cardExpiryDate": ["Invalid expiration date format"]
    },
    "globalErrors": [
      "Unable to process request due to invalid input"
    ]
  }
}

message

A high-level description of the error condition.

This message is intended for logging and diagnostic purposes.

fieldErrors

A map of request fields to validation errors.

Example:

"fieldErrors": {
  "cardNumber": [
    "Card number must contain 13–19 digits"
  ]
}

Use this information to identify specific input fields that failed validation.

Typical causes include:

• Missing required fields

• Incorrect formats

• Invalid enum values

• Invalid data types

globalErrors

Errors that apply to the entire request rather than a specific field.

Example:

"globalErrors": [
  "Pipeline configuration not found"
]

These usually indicate:

• Configuration issues

• Service availability problems

• Business rule violations

Validation Errors

Validation errors occur when request data fails schema or business validation.

Common examples include:

When validation fails:

• isSuccess will be false

• errors.fieldErrors will typically contain details

Common Integration Mistakes

Missing API Key

Requests must include the X-API-KEY header.

Example:

X-API-KEY: your-api-key

If the header is missing or invalid, the API will return an authentication error.

Incorrect Date Formats

Several fields require specific formats.

Examples:

Incorrect formats often result in validation errors.

Missing Required Fields

Different services require different inputs. For example:

Refer to each service guide for required parameters.

Sending Incomplete Pipeline Requests

When using the Pipeline API, the request must include the input sections required by the configured pipeline stages.

For example:

• A pipeline that runs Rules requires a valid rulesRequest

• A pipeline that runs Sentry requires a valid sentryRequest

If required inputs are missing, the request may fail validation.

Logging & Correlation Tips

Effective logging greatly simplifies debugging.

Always Log the Following

When calling the API, log:

• Request endpoint

• Request payload (excluding sensitive card data where applicable)

• HTTP status code

• isSuccess

• errors object

• clientReferenceId

Use clientReferenceId for Traceability

Include a clientReferenceId in requests whenever possible.

Example:

{
  "clientReferenceId": "order-482934"
}

Benefits:

• Correlates requests across internal systems

• Helps MIDSuite support locate transactions

• Simplifies reconciliation and debugging

Capture Raw Responses During Integration

During development and early production rollout, logging the full API response is recommended.

This helps detect:

• Unexpected validation failures

• Service-specific response changes

• Misconfigured pipelines or inputs