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.

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.