generated client sent timestamps as unix seconds - the API expects ISO-8601 and the date filters returned wrong ranges

TL;DR

Convert timestamps to ISO-8601 strings at the serialization layer and regression-test the date filters. The API parses your integer timestamps as something else (or rejects the shape), so every date filter comes back wrong. Fix the serializer once and every call using dates is fixed.

generated client sent timestamps as unix seconds  -  the API expects ISO-8601 and the date filters returned wrong ranges

Steps

1. Confirm what the API wants. Read the provider docs for one date-filter parameter and note the exact expected format, e.g. an ISO-8601 string with a timezone designator. Expected: you have a documented target format, not a guess.
2. Find where the generated client formats dates. Search the client source for epoch/second conversions or integer casts on datetime fields. Expected: you found the single serialization spot (or per-field formatters) where unix seconds get emitted.
3. Change the serializer to emit ISO-8601 strings with an explicit timezone (UTC unless the docs say otherwise). Keep everything else the same. Expected: the code change is small and localized to formatting, not to query logic.
4. Send one manual request with a narrow date window you can predict the answer for (e.g. records created in the last hour). Compare the returned set against what you expect. Expected: the filter now returns exactly the records in that window.
5. Check edge values: records at the window boundary and any code that compares or stores the timestamps after the response. Expected: no off-by-one-hour shifts and no code path that still assumes integers.
6. Regenerate or re-verify the client spec so the fix survives the next codegen run. Pin the date format in the spec or schema if the generator supports it. Expected: regenerating from the spec does not bring the bug back.

Use this when

• Date filters return ranges that look shifted, empty, or nonsensical after a client was generated.
• The generated client sends dates as numbers or the API docs show quoted date strings in examples.
• You control the client generation step and can change the serialization config.

Not for this skill when

• The API documents unix epoch timestamps as accepted (this fix does not apply).
• The real issue is timezones rendering wrong in a UI - that is a display bug, not a wire-format bug.
• Timestamps fail because of clock skew in signatures - see the webhook/signature skills instead.

Variant phrasings

• generated client sent timestamps as unix epoch and the API expects ISO-8601
• date filter returned wrong results because dates were sent as integers
• API expects RFC3339 date strings but client sends unix timestamps

Why it happens

Many code generators default datetime fields to integer epoch serialization because it is unambiguous in some ecosystems. Providers that documented ISO-8601 parse the integer as a malformed string or coerce it, so filters match against garbage dates. Nobody notices at generation time because the request still returns 200.

Edge cases

• Some APIs accept both formats but interpret them differently; always send the documented one.
• Millisecond vs second epochs: if you keep epoch anywhere, say so explicitly, since a 1000x unit mismatch is the same class of silent breakage.
• APIs that require the timezone offset, not just a Z suffix - "Z" and "+00:00" are not identical to every parser.

Provenance

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