We’re getting 422 Unprocessable Entity errors when creating incident cases via the Case Management REST API from our automated support workflows. The API response indicates missing required fields, but our payload includes all fields documented in the API guide.
Error response:
{
"error": "Validation failed",
"details": "Required field 'incidentCategory' missing",
"statusCode": 422
}
Our payload structure follows the documentation, but we’re unsure if there are additional required fields not mentioned in the basic examples. We’ve checked the OpenAPI specification, but the schema validation seems stricter than what’s documented. This is blocking our case automation workflows for incident routing. Are there hidden required field mappings in Case Management that aren’t obvious from the standard API docs?
Also check if your Case Management has field mapping rules configured. Sometimes the API accepts a different field name than what’s stored internally, and the mapping configuration can have validation rules that reject payloads if certain mapped fields are missing. Look in the Case Management admin console under ‘Field Mappings’ for your incident case type.
Good point about the field naming. I checked and we’re using ‘incidentCategory’ in camelCase as shown in the docs. The API version is v2 which matches our Case Management module version. Could this be related to custom fields that were added to our Case Management configuration? We have several custom incident fields that might have required validation rules.
Custom fields are definitely a likely culprit. When you extend the Case Management data model with custom fields and mark them as required in the case type configuration, those requirements apply to API calls even if they’re not in the base OpenAPI spec. You need to check your case type definitions in the Case Management configuration to see which fields are marked mandatory. The OpenAPI spec only covers the base schema, not your customizations.
The issue you’re experiencing is due to a combination of OpenAPI spec interpretation and custom field requirements in your Case Management configuration. Here’s how to resolve it:
First, understand that the OpenAPI specification you’re referencing shows the base schema, but your actual Case Management instance has additional required field mappings. To identify all required fields:
-
Check Case Type Configuration: In Case Management admin, navigate to your incident case type definition. Look for fields marked with ‘Required’ validation. These must be included in your API payload even if not in the base OpenAPI spec.
-
Verify Field Mapping: The field name in your payload must exactly match what Case Management expects. Use this structure:
{
"caseTypeId": "incident",
"incidentCategory": "technical",
"priority": "high"
}
- Download the Complete Schema: Instead of relying on documentation examples, download the actual OpenAPI spec from your Case Management instance endpoint at
/api/v2/openapi.json. This includes your custom fields and their validation rules.
For payload schema validation, implement a pre-submission validation step in your workflow. Before calling the Case Management API, validate your payload against the OpenAPI schema using OutSystems’ JSON validation actions. This catches missing required fields before the API call.
The specific error about ‘incidentCategory’ suggests this field is required in your case type configuration but was either:
- Missing from the payload entirely
- Named incorrectly (check for typos or case sensitivity)
- Sent with an invalid value that doesn’t match the allowed enum values
To properly map required fields, create a reference structure in your workflow that includes:
- All base Case Management required fields (caseTypeId, title, description, priority)
- Your custom required fields from case type configuration
- Any conditional required fields (fields that become required based on other field values)
For OpenAPI spec usage, implement automatic schema validation in your integration layer. OutSystems can consume the OpenAPI spec and generate client-side validation before making the API call. This prevents 422 errors by catching validation issues early.
Finally, enable detailed error logging in your Case Management API integration. The full error response often includes a ‘fieldErrors’ array that lists all validation failures, not just the first one. This helps you identify multiple missing required fields in a single test rather than fixing them one at a time.
I’d recommend using the API’s schema validation endpoint if available. Some Case Management implementations expose a /validate endpoint where you can POST your payload structure before actually creating the case. This returns detailed validation errors including all missing required fields. It’s much faster than trial-and-error with actual case creation attempts.
The 422 error typically means the payload structure is correct but field-level validation is failing. Check if ‘incidentCategory’ is actually named differently in the OpenAPI spec - sometimes the documentation uses camelCase but the API expects snake_case or a different format. Also verify you’re using the correct API version endpoint, as field requirements can change between versions.