---
title: "Parse Workday REST & SOAP BP Validation Errors — Kiweely"
description: "How to parse HTTP 400 validation JSON payloads in Workday REST APIs vs. Validation_Fault and Processing_Fault XML in SOAP, plus handling warnings."
url: https://kiweely.com/guides/workday-business-process-validation-errors-rest-soap-responses
---

# Parsing Workday Business Process Custom Validation Errors Returned by REST and SOAP APIs

Workday REST APIs return HTTP 400 JSON payloads containing an errors array with code, field, path, and severity (Critical or Warning), whereas Workday SOAP Web Services return HTTP 500 envelopes containing Validation\_Fault (with Xpath) or Processing\_Fault elements.

-   **Checked** against Workday on November 15
-   Applies to **Workday REST & SOAP APIs**
-   7 min read
-   Published November 15
-   By Kiweely

Workday REST APIs surface schema, field, and custom business process validation failures as `HTTP 400 Bad Request` JSON objects with a top-level `error` summary and an `errors[]` array (`code`, `error`, `field`, `path`, `severity`), whereas Workday Web Services (SOAP) return `HTTP 500 Internal Server Error` envelopes carrying either `<wd:Validation_Fault>` (for input and rule violations, complete with `<wd:Xpath>`) or `<wd:Processing_Fault>` (for runtime execution failures). Treating both protocols with generic HTTP status catch blocks turns clear user-correctable rules—such as time-off increment minimums or hiring-freeze blocks—into opaque `"500 Server Error"` banners.

Because Workday evaluates custom condition rules configured on **Maintain Custom Validations**, **Edit Time Off**, and **Configure Optional Fields** identically across the browser UI and web services, an external screen or integration can map every error cleanly back to the exact input control if it parses the underlying error model rather than scraping human-readable strings.

## REST vs. SOAP Validation Error Envelope Comparison

Use this structural map when normalizing errors across endpoints that mix Workday REST (`absenceManagement`, `expense`, `staffing`) and Workday SOAP (`Human_Resources`, `Absence_Management`, `Financial_Management`):

| Attribute | Workday REST API (`VALIDATION_ERROR_MODEL`) | Workday SOAP API (`Validation_Fault`) | Workday SOAP API (`Processing_Fault`) |
| --- | --- | --- | --- |
|  **HTTP Status Code** | `400 Bad Request` | `500 Internal Server Error` | `500 Internal Server Error` |
|  **Top-Level Discriminator** | JSON `errors[]` array under root `error` string | `<faultcode>SOAP-ENV:Client.validationError</faultcode>` + `<detail><wd:Validation_Fault>` | `<faultcode>SOAP-ENV:Server.processingError</faultcode>` + `<detail><wd:Processing_Fault>` |
|  **Machine Error Code** | `errors[i].code` (e.g., `S6`, `A6`, `A1023`) | `<wd:Code>` inside `<wd:Validation_Error>` | `<wd:Code>` inside `<wd:Processing_Fault>` |
|  **Field / Element Pointer** | `errors[i].field` and JSON path `errors[i].path` | `<wd:Xpath>` pointing to the failing XML node | None (operation-level fault) |
|  **Rule Text & Dynamic Context** | `errors[i].error` and optional `internalMessage` | `<wd:Message>` and `<wd:Detail_Message>` | `<wd:Detail_Message>` |
|  **Warning vs. Critical Split** | `errors[i].severity` (`"Critical"` or `"Warning"`) | Critical rules throw fault; warnings allow completion unless configured as critical | Always aborts transaction |

## Anatomy of a Workday REST `HTTP 400` Validation Payload

Every Workday REST OpenAPI specification binds `400` responses to `VALIDATION_ERROR_MODEL_REFERENCE`, where each item in `errors` follows `ERROR_MODEL_REFERENCE`. Never drive client logic by regex-matching the English `error` message—Workday administrators edit custom validation text in **Maintain Custom Validations** or **Maintain Time Off Data Validation Custom Text**, and worker locales translate delivered messages dynamically. Branch on `code`, `severity`, and `path` instead:

json

```
{
  "error": "invalid request: validation errors",
  "errors": [
    {
      "code": "A1023",
      "error": "For 2026-11-24, the Daily Quantity for Vacation should be in increments of 4 Hours.",
      "field": "dailyQuantity",
      "path": "days[0].dailyQuantity",
      "severity": "Critical",
      "internalMessage": "Time Off Entry Validation failed on Initiation step."
    }
  ]
}
```

### System Codes (`S*`) vs. Application Validation Codes

Workday REST error codes split into two distinct layers:

1.  **Framework System Codes (`S3` through `S32` on `HTTP 400`):** Returned before business logic runs. Common culprits include `S5` (*Failed To Parse Request* for malformed JSON types), `S6` (*Invalid Reference ID* when a 32-character hexadecimal WID or `Type=Value` reference ID is empty or malformed), `S7` (*Invalid Reference Type*), `S14` (*Bulk Limit Exceeded*), `S28` (*Expired ID*), and `S31` (*Invalid Instance* when passing a Cost Center WID into a Supervisory Organization field).
2.  **Application & Custom Business Process Codes:** Returned when the payload is structurally valid JSON with valid WIDs, but violates a domain rule—such as `A6` (*Value required in field*), a **Configure Optional Fields** rule with **Enforce Required in Web Services** checked, a hiring freeze on a target `Supervisory Organization`, or a custom condition rule attached to the **Initiation** step of a business process.

### Sequential Short-Circuiting

Workday’s REST validation pipeline executes in strict stages and **halts immediately at the first `Critical` failure**. If a request contains both an invalid reference ID (`S6`) on `timeOffType` and a negative `dailyQuantity` that violates a custom Absence rule, the first `400` response returns only `S6`. Your client will not see the custom Absence validation until `S6` is fixed and the request is resubmitted.

## Pre-Flighting and Bypassing Warnings in REST (`x-validate-only` and `wd-warning-action`)

Two Workday-specific REST headers let user-facing applications match the exact two-step behavior workers see in the Workday browser UI:

### 1\. Dry-Run Validation with `x-validate-only: 1`

Before showing an employee a final confirmation screen on `POST`, `PUT`, `PATCH`, or `DELETE`, send `x-validate-only: 1`. Workday evaluates operation security, field-level security, prompt resource constraints, currency rules, **Configure Optional Fields** rules, and business process validations without persisting any event or triggering downstream notifications:

Works

```
POST /api/absenceManagement/v2/tenant_dpt1/workers/3aa5550b7fe348b98d7b5741afc65534/requestTimeOff HTTP/1.1
Host: wd5-services1.workday.com
Authorization: Bearer <employee_oauth_access_grant>
Content-Type: application/json
x-validate-only: 1
```

If all checks pass, Workday returns `HTTP 200 OK` without creating a Business Process event. Remove `x-validate-only` (or set `x-validate-only: 0`) when the user confirms submission.

### 2\. Persisting Data Past Non-Critical Warnings with `wd-warning-action`

In the Workday UI, a **Warning** validation displays an orange alert that the worker can acknowledge and submit past, whereas a **Critical** validation displays a red hard stop. Over REST, however, **any** validation failure—even `severity: "Warning"`—blocks persistence by default and returns `HTTP 400`.

Once the user reviews the warning text and chooses to proceed, resubmit with `wd-warning-action: updateonwarning`:

Works

```
POST /api/absenceManagement/v2/tenant_dpt1/workers/3aa5550b7fe348b98d7b5741afc65534/correctTimeOffEntry HTTP/1.1
Host: wd5-services1.workday.com
Authorization: Bearer <employee_oauth_access_grant>
Content-Type: application/json
wd-warning-action: updateonwarning
```

Workday persists the Business Process event (`HTTP 200` / `201`) and still includes the `errors[]` array with `"severity": "Warning"` in the success payload so your application can log or display the acknowledged warning.

Mutually Exclusive Headers

Never send `wd-warning-action: updateonwarning` and `x-validate-only` on the same HTTP request—even with `x-validate-only: 0`. Workday rejects the combination immediately. Also verify exact spelling: `updateonwarning` is the only valid value, and a misspelled header name silently reverts to blocking on warnings.

## Anatomy of Workday SOAP `Validation_Fault` vs. `Processing_Fault`

Workday SOAP Web Services (`urn:com.workday/bsvc`) return `HTTP 500` for every fault—authentication failures, missing WIDs, custom business process blocks, and transient server timeouts alike. Never trigger automatic retry loops on a raw SOAP `HTTP 500` without inspecting `<faultcode>` and `<detail>` first.

### `Validation_Fault`: Input, Reference ID, and Custom BP Rules

When a SOAP request such as `Enter_Time_Off` or `Change_Job` violates XSD constraints, passes an unresolvable reference ID, or trips a Critical custom validation on the Business Process Initiation step, Workday returns `SOAP-ENV:Client.validationError` with one or more `<wd:Validation_Error>` elements:

xml

```
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault xmlns:wd="urn:com.workday/bsvc">
      <faultcode>SOAP-ENV:Client.validationError</faultcode>
      <faultstring>Validation error occurred. Time Off request exceeds Maximum Unpaid Time Off Units Allowed.</faultstring>
      <detail>
        <wd:Validation_Fault>
          <wd:Validation_Error>
            <wd:Message>Time Off request exceeds Maximum Unpaid Time Off Units Allowed (0 Hours) for Vacation Plan.</wd:Message>
            <wd:Detail_Message>Element 'wd:Enter_Time_Off_Data' violated custom or plan validation on step Initiation.</wd:Detail_Message>
            <wd:Xpath>/ns0:Enter_Time_Off_Request[1]/ns0:Enter_Time_Off_Data[1]/ns0:Run_Time_Off_Validations[1]</wd:Xpath>
            <wd:Code>01004</wd:Code>
          </wd:Validation_Error>
        </wd:Validation_Fault>
      </detail>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

Extract all four child nodes from every `<wd:Validation_Error>` item (`maxOccurs="unbounded"` in the WSDL):

-   **`<wd:Xpath>`:** Pinpoints the exact repeating row (for example, `ns0:Time_Off_Entry_Data[3]/ns0:Requested[1]`) when submitting multi-day or multi-line requests.
-   **`<wd:Message>`:** The primary validation description or custom message configured by the tenant administrator, safe to surface to an end user after stripping internal XML element names if present.
-   **`<wd:Detail_Message>`:** Low-level schema or element context for developer diagnostics.
-   **`<wd:Code>`:** Stable error identifier for programmatic routing.

### `Processing_Fault`: Concurrency Locks and Execution Failures

When `<detail>` contains `<wd:Processing_Fault>` (`Detail_Message` and `Code`, with no `Xpath`), the XML payload passed validation, but execution failed inside the tenant—for example, a record lock from a concurrent staffing event on the same worker or an internal timeout. Log `Processing_Fault` separately from user input errors and inspect whether an in-progress Business Process event already locks the target worker.

## Implementation Checklist for Mapping Errors to Clean User Feedback

1.  **Parse before retrying:** Never retry `HTTP 400` (REST) or `SOAP-ENV:Client.validationError` / `SOAP-ENV:Client.authenticationError` (SOAP). High volumes of repeated invalid requests trigger Workday’s system guardrails and result in temporary `HTTP 429` throttling.
2.  **Map REST `path` and SOAP `Xpath` to form fields:** Maintain a dictionary mapping API paths (`days[0].dailyQuantity` or `Time_Off_Entry_Data[1]/Date`) to UI field labels so inline errors land next to the offending date or amount input.
3.  **Separate Warning confirmation from Critical blocks:** When REST returns `HTTP 400` where every entry in `errors[]` has `"severity": "Warning"`, render an explicit confirmation prompt with the warning text and replay the request with `wd-warning-action: updateonwarning` only if the user confirms.
4.  **Verify `Configure Optional Fields` parity:** If a field is required in the Workday UI for `Employee As Self` but optional over REST/SOAP, check **Configure Optional Fields** in Sandbox to see whether **Enforce Required in Web Services** is cleared.

Building external forms or conversational workflows on top of Workday requires handling these validation contracts cleanly on every tenant. [Kiweely Leaf](https://kiweely.com/leaf) and [Kiweely Bridge](https://kiweely.com/bridge) (both coming next) inspect your tenant’s business process validations, run dry-run checks under each signed-in employee’s own Workday OAuth grant, and surface Workday’s exact field-level rules and out-of-band browser approval cards before any write commits.

## Frequently asked questions

### Why does a Workday REST API request fail with HTTP 400 when a validation rule is configured only as a Warning?

By default, Workday REST endpoints block persistence whenever any validation condition—Critical or Warning—fires. To persist a transaction while acknowledging non-blocking warnings, send the HTTP header wd-warning-action: updateonwarning on your POST, PUT, PATCH, or DELETE call.

### Why didn't Workday return all five validation errors in my payload on the first API call?

Workday evaluates validations sequentially across schema syntax, reference IDs, required fields, and business process rules, halting immediately upon the first Critical failure. Subsequent validation stages only execute once earlier critical errors are fixed.

### What is the difference between Validation\_Fault and Processing\_Fault in Workday SOAP Web Services?

Validation\_Fault contains one or more Validation\_Error blocks with Message, Detail\_Message, Xpath, and Code when input data violates schema rules, reference IDs, or custom validations. Processing\_Fault signals an execution-time or system state failure with only Detail\_Message and Code.

### Do custom required fields from Configure Optional Fields trigger errors in REST and SOAP APIs?

Only when the Enforce Required in Web Services checkbox is selected on the Configure Optional Fields task for that functional area and matching security group or country criteria.

## Sources checked

-   [Reference: REST API Error Messages](https://developer.workday.com/documentation/GUID-6f06b090-c7b5-47cc-b929-d2a1f1116eef-enHYPHENus)
-   [Concept: Warning Action REST API Header](https://developer.workday.com/documentation/GUID-83e641fd-e05f-47a7-b585-128bc7c96fe4-enHYPHENus)
-   [Concept: Validate Only Mode for REST APIs](https://developer.workday.com/documentation/rni1611281077170)
-   [Reference: Workday Web Services Error Messages](https://developer.workday.com/documentation/hug1399941147933)
-   [Course Manual: Validations in Workday](https://doc.workday.com/workday-education/en-us/course-manuals/hcm-core-supplemental-for-administrators/validations-in-workday.html)

## Related guides

[All guides](https://kiweely.com/guides)

-   [### Authenticating Workday SOAP Web Services with a User-Delegated OAuth Bearer Token Send Workday SOAP requests with an HTTP Authorization Bearer header issued from a user-delegated OAuth 2.0 Authorization Code grant and leave the SOAP XML Header element empty. Workday evaluates both the API Client Functional Area scope and the signed-in worker’s Integration Permissions.](https://kiweely.com/guides/workday-soap-api-bearer-token-user-delegated-oauth)
-   [### Diagnosing Workday REST API 403 Forbidden: Missing Client Scope vs. Worker Domain Security A Workday REST API 403 Forbidden means OAuth authentication succeeded, but authorization failed at one of five checkpoints: API Client Functional Area scope, stale pre-edit access grant, Report/Task Domain Security Policy, Business Process Security Policy, or unactivated pending policy changes.](https://kiweely.com/guides/workday-rest-api-403-forbidden-user-security-vs-client-scope)
-   [### How Workday Audits Business Processes Initiated via REST or SOAP Web Services Workday records every web-service-initiated business process in the Full Process Record and View Audit Trail under the authenticated Workday account. Whether that audit trail shows a real employee or a shared system bot depends on whether the caller used user-delegated OAuth or an ISU.](https://kiweely.com/guides/workday-business-process-audit-trail-initiated-via-web-service)
-   [### Should I use RaaS, WQL or the REST API to extract data from Workday? Use RaaS for a saved report’s output, WQL for a filtered, grouped or paged extract of up to 1 million rows, and REST for small, low-latency reads of one resource. Limits and sources are in the table.](https://kiweely.com/guides/workday-raas-wql-rest)

### More guides on Integrations and APIs

[All 89 guides](https://kiweely.com/guides#integrations)

-   [Approving, Denying, and Sending Back Workday Business Process Steps via REST and SOAP APIs](https://kiweely.com/guides/workday-business-process-approve-deny-rest-soap-api)
-   [How Workday Studio PutIntegrationMessage Severity Levels Control Completed-with-Warnings vs. Aborted Runs](https://kiweely.com/guides/workday-studio-error-severity-critical-warning-abort)
-   [How to Fix Workday Studio SDKProfile Not Current and Unsigned Software Startup Errors on Mac and Windows](https://kiweely.com/guides/workday-studio-sdkprofile-not-current-unsigned-macos-errors)
-   [How to Authenticate Workday Studio and External Tools Using an OAuth API Client with PKCE (When SSO Blocks Passwords)](https://kiweely.com/guides/workday-api-client-pkce-sso-without-workday-password)
-   [Workday PECI vs. PICOF Payroll Connectors: How Effective-Dated Stack and Retro Changes Export](https://kiweely.com/guides/workday-peci-picof-payroll-connector-change-detection)
-   [Why does my Workday Accounting Journal EIB fail? Balancing, worktag and period errors](https://kiweely.com/guides/workday-financials-accounting-journal-eib-validation-errors)
-   [How to Find Every Domain and Web Service Permission an ISU Needs in Workday (Without Guesswork)](https://kiweely.com/guides/workday-isu-permissions-activate-pending-security-policy-changes)
-   [How to Fix The Load Contains a Duplicate Key and Invalid Reference ID Errors in Workday EIB](https://kiweely.com/guides/workday-eib-duplicate-key-reference-id-errors)

### From the blog on Integrations and APIs

[All posts](https://kiweely.com/blog)

-   [Workday REST API vs. SOAP Web Services: Why Setup Work Still Needs the Task Screen](https://kiweely.com/blog/workday-rest-api-vs-soap-coverage-gaps)
-   [Untangling Inherited Workday Studio Integrations: A Practical Modernization Playbook](https://kiweely.com/blog/untangling-inherited-workday-studio-integrations)
-   [Why Most Workday Studio Integrations Ship Without Tests](https://kiweely.com/blog/workday-studio-integrations-without-tests)

## Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

[Start for free](https://kiweely.com/download) [See how it works](https://kiweely.com/vine/how-it-works)

## Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.
