type-mismatch

Description

A value in the request could not be converted to the expected type. This applies to query parameters, path variables, headers, and request body fields. For example, a string was provided where a number was expected, a number was provided where an object was expected, or a date value does not match the required format.

Response Examples

Parameter type mismatch

Code
{
  "type": "https://docs.kordiam.app/docs/errors/type-mismatch",
  "title": "Type Mismatch",
  "status": 400,
  "detail": "Parameter 'id' should be a number but received 'abc'",
  "instance": "/api/v2/platforms/abc",
  "traceId": "abc-123-def",
  "parameterName": "id",
  "expectedType": "a number",
  "actualValue": "abc"
}

Request body type mismatch

When the mismatch occurs inside the JSON request body, the response includes an errors array with the field path:

Code
{
  "type": "https://docs.kordiam.app/docs/errors/type-mismatch",
  "title": "Type Mismatch",
  "status": 400,
  "detail": "Expected an object for 'user' but received a number",
  "instance": "/api/v2/elements",
  "traceId": "abc-123-def",
  "errors": [
    {
      "scope": "body",
      "path": "tasks[0].user",
      "code": "type-mismatch",
      "message": "Expected an object for 'user' but received a number"
    }
  ]
}

Common Causes

• Passing a string value for a numeric parameter (e.g., id=abc instead of id=42)
• Using an invalid date format (e.g., 2026-13-01 or 01/01/2026 instead of 2026-01-01)
• Supplying a non-boolean value for a boolean parameter (e.g., active=yes instead of active=true)
• Sending a primitive value (number, string) for a field that expects an object (e.g., "user": 123 instead of "user": {"id": 123})
• Sending a single value where an array is expected, or vice versa

How to Fix

1. Check the expected type for each field or parameter in the API reference.
2. For parameter mismatches, read the detail field, which identifies the problematic parameter and the expected type.
3. For request body mismatches, inspect the errors array — each entry includes the path to the problematic field and a message describing the expected vs. actual type.