Sample
Handle Faraday JSON response deserialization and error middleware ordering without unparsed string payloads or type mutation traps
sha256:dfee68bbd326424c9c702d0cf42e9ddcaf36879dbd2f497a522dcfbc402a3938
PUBLISHED
L3_CONTRACT_PASS
MIT-0
Case
- Goal
- Handle Faraday JSON response deserialization and error middleware ordering without unparsed string payloads or type mutation traps HOW
- Packages
- faraday 2.14.3
- Environment
- ruby
- Created
- 2026-08-17T02:38:41Z
Commonly assumed
Declaring response :json before response :raise_error in a Faraday connection ensures 4xx and 5xx error response bodies are deserialized into Ruby Hashes on rescued client and server exceptions.
The sample's author recorded this as what a developer or model would expect here. The contract below is what actually ran.
Contract
- Rescuing a client error from a Faraday connection with response :json declared before response :raise_error leaves error.response[:body] as an unparsed JSON String rather than a deserialized Hash because response middleware unwinds in reverse order.
- Declaring response :raise_error before response :json allows response :json to decode 4xx and 5xx payloads into Hashes before exceptions are raised.
- Symbol keys and Symbol values in request payloads are deserialized as String keys and String values after a JSON round trip unless symbolize_names parser option is configured.
- Empty response bodies and whitespace-only JSON responses deserialize to nil rather than empty Hashes or empty Strings.
- Responses with non-JSON Content-Type headers such as text/plain are left as raw Strings by response :json.
- Configuring preserve_raw: true stores the original raw JSON string in env[:raw_body] while env.body holds the parsed Hash.
Files
- Gemfile
- Gemfile.lock
- NOTES.md
- csx.json
- src/client.rb
- test/contract.rb
Download the verified artifact (tar.gz) — the exact bytes the contract ran against
Origin Seeder
Verification receipts
- ruby 3 · CONTAINER_RUN · compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS · rubygems@1 · 2026-08-17 · ed25519:d91480838ac982c9