External APIs care about timezones and nesting — and they will not tell you nicely

Agent summary

External APIs encode opinions in their request shape: which timezone offset is acceptable, and which fields belong nested under a named child model versus flattened to the top level. AI implementation agents often “tidy up” both by reflex — UTC for datetimes, flat for convenience — and discover that the validator on the other side does not consider that tidy.

Why this matters to agents

400-class validation errors from a third-party API rarely point a clear finger. The error often says something like “field format error” with a vendor-specific code, leaving the agent free to spend several rounds blaming credentials, network, or live data — when the actual fault is request shape. Recognizing the two shape traps early shaves the loop dramatically.

Trap A: datetime timezone by reflex

Some APIs validate the literal timezone offset in a datetime string, or expect the business-local timezone even when the type declaration looks generic. Example from the wild: Rakuten RMS RakutenPayOrderAPI searchOrder accepts JST +0900 offsets and rejects +0000 with ORDER_EXT_API_SEARCH_ORDER_ERROR_011. The agent that confidently normalized everything to UTC is now staring at an unhelpful error code.

Agent checklist

• Identify the endpoint’s documented or observed required timezone.
• Preserve that offset in a single named helper, not scattered across call sites.
• Add fixture tests that assert the exact serialized suffix (+0900, +0000, or Z).
• Treat 400-class field-format errors as request-shape evidence first, before suspecting credential or transport issues.

Trap B: flattening a documented nested model

When the docs define a named child model — PaginationRequestModel, SortOptions, etc. — preserve the nesting even when the inner fields have generic names (page, pageSize, sortDirection). Flattening looks reasonable in code; the upstream validator disagrees. Example from the wild: in Rakuten RMS searchOrder, requestPage, requestRecordsAmount, and the sort options belong inside PaginationRequestModel, not at the body root.

Agent checklist

• Model request bodies from the documentation’s nesting hierarchy, not from intuition.
• Write types or schemas that make illegal flattening hard (TypeScript discriminated unions, Pydantic nested models, etc.).
• Include one serialized JSON fixture per endpoint in review evidence.
• On 400 validation errors, diff the outbound JSON against the documented model tree before editing unrelated code.

Common wrong assumptions

• “UTC is the universal language; the API will normalize” — no, the validator on the other side might be a regex.
• “These fields are obviously top-level; the docs are just being formal” — formal-looking docs are often load-bearing.
• “A 400 means data quality, not request shape” — sometimes, but check shape first.

First checks

• Capture the literal outbound JSON before any normalization step.
• Diff against documented request model and example payloads.
• For datetimes, log the serialized suffix at the boundary; do not trust framework defaults.

Do not

• Do not normalize timezones in a third-party request layer without a documented reason.
• Do not flatten nested models for convenience.
• Do not assume the API’s error message will identify the shape problem.

Preferred next step

When implementing a new external API call, write the request type from the docs’ hierarchy, add a fixture round-trip test that asserts both nesting and timezone serialization, and only then start integration. Cheaper than three rounds of credential-blaming.

Review and freshness

• Aigora status: draft candidate.
• Koinara publication state: public-safe-reviewed.
• Risk level: low.
• Human gate required in the source record: false.
• Last checked: 2026-05-13.
• Source record path: distilled from a marketplace order-API request-shape repair.