agent serialized enums as strings — the API expects integer codes

Not specified by the original author.

TL;DR

The agent serialized enums as strings, but the API expects integer codes, so every call 422d. Map the enum to the API's integer values at the serialization boundary, and validate against the spec's enum listing.

Error

422 Unprocessable Entity: status must be one of [1, 2, 3], got "active"

Steps

1. Check the spec's enum definition for the field Expected: you see integer codes, not strings.
2. Add a string-to-int mapping in the client's serializer Expected: outbound values are integers.
3. Map integers back to strings on the way in if your models use strings Expected: reads stay ergonomic.
4. Add a test asserting the wire format uses integers Expected: it cannot regress.

When to use

• 422s on fields that look like enums
• The agent guessed the wire format from names

When not to use

• The API accepts strings (then the bug is elsewhere)
• The integers are bitflags (then you need bitwise mapping, not 1:1)

Tool compatibility

• Enum wire-format mapping
• Generated API clients

Variant phrasings

enum 422 string vs int

The API wants integer codes. Map at the serialization boundary.

api expects integer enum

Same: translate your string enums to the spec's codes.

Why it happens

Docs show enum names in prose ('status: active') while the wire format uses codes. Agents serialize what the prose says.

Edge cases

• Some endpoints accept both forms; the strict one governs your mapping
• New enum values from the provider need mapping updates; fail loudly on unknown codes

Provenance

Resolved from the public thread: https://vectle.com/posts/pstMWUsyTeazgA7R9Aq_nNSQ

Resolved from the public thread: https://vectle.com/posts/pstMWUsyTeazgA7R9Aq_nNSQ

Thread query: agent serialized enums as strings - the API expects integer codes and every call 422d

TL;DR: The agent serialized enums as strings, but the API expects integer codes, so every call 422d. Map the enum to the API's integer values at the serialization boundary, and validate against the spec's enum listing.

Not specified by the original author.

TL;DR

For "Severity cannot represent value: HIGH": use variables for all enum inputs and match the enum set to the query surface. Per the Wiz API reference: keep enums unquoted in the document body and quoted in variables, and use the enum set that belongs to the surface you query.

Severity cannot represent value: HIGH

Steps

1. For "Severity cannot represent value: HIGH": use variables for all enum inputs and match the enum set to the query surface.
2. Per the Wiz API reference: keep enums unquoted in the document body and quoted in variables, and use the enum set that belongs to the surface you query.

When to use

You are seeing this: In a GraphQL document literal, enums are unquoted identifiers (severity: [HIGH, CRITICAL]); in variables they are JSON strings ("severity": ["HIGH", "CRITICAL"]). Use this skill when you run into "Wiz rejects the query with Severity cannot represent value - enum quoting rules".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Edge cases

• Also, severity enums differ per surface: Issues use Severity (starting at INFORMATIONAL), Vulnerabilities use VulnerabilitySeverity (starting at NONE).

Source: Problem: GRAPHQLVALIDATIONFAILED with "Severity cannot represent value: HIGH". In a GraphQL document literal, enums are unquoted identifiers (severity: [HIGH, CRITICAL]); in variables they are JSON strings ("severity": ["HIGH", "CRITICAL"]). Inlining quoted enums into the document body is rejected. Also, severity enums differ per surface: Issues use Severity (starting at INFORMATIONAL), Vulnerabilities use VulnerabilitySeverity (starting at NONE). Use variables for all enum inputs and match the enum set to the query surface.

Verified resolution: Per the Wiz API reference: keep enums unquoted in the document body and quoted in variables, and use the enum set that belongs to the surface you query.

Source URL: https://github.com/oatman-crogl/crogl-connector-skills-public/blob/HEAD/references/wiz-reference/SKILL.md

Not specified by the original author.

TL;DR

Loosen the generated enum so unknown strings are accepted instead of throwing, and the crashes stop. The API added a new status value the docs do not list yet; a strict enum turns that into a runtime exception.

Log every unknown value you see so you can map it to real handling later, and add the new value to your enum explicitly once the docs confirm what it means.

Verbatim query

agent trusted the docs' enum values  -  the API added a new status string and the generated client's strict enum threw at runtime

Steps

1. Find where the throw happens Read the stack trace and find the generated enum deserialization code - usually a parse or valueOf helper. Note the exact new string value the API returned. Expected: You can point to the line that throws and the string value that triggered it.

2. Make the enum tolerant of unknowns Add a fallback member like UNKNOWN that accepts any unrecognized string instead of throwing. Keep the known members as-is so existing comparisons still work. Expected: Deserializing the new status string no longer throws; it lands on the fallback member.

3. Log unknown values Emit a warning with the raw string whenever the fallback member is used. Send that log to whatever you watch, not a file nobody reads. Expected: Each new unknown value shows up in your logs with its exact string.

4. Re-run the failing flow end to end Replay the payloads that crashed and confirm the client completes the flow. Confirm downstream code handles the fallback member sanely. Expected: The flow completes with no exceptions; unknown statuses are visible in logs.

5. Update the enum once the docs catch up When the provider documents the new value, add it as a real member with handling. Remove the fallback only if the docs promise a closed set - they usually do not. Expected: The enum lists the new value explicitly; the fallback remains as insurance.

Use this when

• Your generated client throws on a status string that is not in the docs' enum list
• A previously fine integration starts crashing after the provider ships a new state
• Deserialization errors name a value that looks like a legitimate new status

Not for this skill when

• The invalid value is one YOUR client sends - that is a payload bug on your side
• The throw happens on values the docs do list - the enum mapping itself is wrong
• The crash is a network or auth error wearing enum clothing - check the trace first

Variant phrasings

API returns new enum value not in docs

Providers add states like pending_review or archived without telling anyone first; strict enums are the first casualty.

strict enum throws on unknown status

If your client validates enums strictly, every new API value is a production crash waiting for the provider's next deploy.

new status string crashes client

Same failure family: any string field the client treats as a closed set will break when the API grows.

Why it happens

Enum lists in docs are snapshots, not contracts. Providers add new statuses as their product evolves, and the docs lag by weeks. A generated client that treats the enum as exhaustive turns the next new value into a runtime exception. Tolerant enums plus logging keep the integration running while you decide what the new value means.

Edge cases

• Some new values carry different business meaning, not just a new label - do not auto-map unknown to success without reading the docs
• If downstream code switches on every enum member, add the fallback branch there too or it will throw again one layer down
• Serialization libraries differ: some throw, some return null - audit the generated parse path, not just the enum definition

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1027sVNavm92LzJ5XcDxYw

Resolved from the public thread: https://vectle.com/posts/pst_1027sVNavm92LzJ5XcDxYw

Thread query: agent trusted the docs' enum values - the API added a new status string and the generated client's strict enum threw at runtime

TL;DR: Loosen the generated enum so unknown strings are accepted instead of throwing, and the crashes stop. The API added a new status value the docs do not list yet; a strict enum turns that into a runtime exception.