Fixing a validation error

Read error.errors first. Each item identifies the public parameter, its location, and a stable reason. The message is display text and must not drive application logic.

Workflow

1. Keep correlation_id and trace_id for support.
2. Group errors by param.
3. Fix required errors before format or dependency errors.
4. Do not retry automatically: IKW-REQ-* errors require changing the request.

Examples

Missing body property:

{"param":"currency","location":"body","reason":"required"}

Invalid query value:

{"param":"limit","location":"query","reason":"out_of_range","minimum":1,"maximum":100}

Invalid path value:

{"param":"payout_id","location":"path","reason":"invalid_format","expected":"UUID"}

Missing header:

{"param":"Idempotency-Key","location":"header","reason":"required"}

Invalid ops header:

{"param":"X-Ops-Merchant-Id","location":"header","reason":"invalid_format","expected":"UUID"}

Malformed JSON or wrong type:

{"param":"amount","location":"body","reason":"type_mismatch","expected":"integer"}

Nested body:

{"param":"destination.mobile_money.operator","location":"body","reason":"unsupported_value","allowed_values":["orange_money","wave","mtn_momo"]}

Unknown field:

{"param":"destination.mobile_money.operatr","location":"body","reason":"unknown_field","suggestion":"destination.mobile_money.operator"}

Mismatch:

{"param":"merchant_id","location":"header","reason":"mismatch"}

Ops:

{"param":"execution_id","location":"body","reason":"invalid_format","expected":"UUID"}

Routing:

{"param":"provider_code","location":"path","reason":"unsupported_value","allowed_values":["orange_money","wave","mtn_momo"]}

Terminal:

{"param":"serial_number","location":"body","reason":"required"}

JavaScript

try {
  await ikawaari.payouts.create(payload)
} catch (error) {
  if (error.name === 'ValidationError') {
    const operatorError = error.getFirstFieldError(
      'destination.mobile_money.operator'
    )
  }
}

The SDK continues parsing legacy envelopes during the transition, but new code should use errors, param, and reason.