Retool REST API Error Handling: Fix Error Transformers

Retool REST API error handling trips up a lot of builders. You set up an Error Transformer, you preview it in the query editor and it looks perfect — but when the query actually runs inside your app, the raw JSON blob gets shown to the user instead of your clean error message. Or worse, the transformer fires on every response, including successful 200s. This guide walks you through exactly how Retool's error transformer works for REST APIs, what a previous bug caused, and the right pattern to handle 400 errors cleanly today.

What Is the Error Transformer in Retool?

The Error Transformer is a JavaScript block you can enable on any Retool query. Its purpose is to intercept error responses and let you reshape or extract specific fields before Retool surfaces them to the user. For REST APIs that return structured error bodies — like Stripe-style responses — this is the primary tool for showing a human-readable message instead of a raw JSON dump.

A typical error response you might want to handle looks like this:

{ "error": { "kind": "validation_error", "message": "Form cannot be Completed without an Index" } }

Without an error transformer, Retool will display the entire JSON object to the user in a notification. With one, you can return just data.error.message — a single clean sentence.

Why Your Error Transformer Wasn't Working (The Bug)

If you set this up before mid-2020 and found that the transformer output appeared correctly in the query preview but the full JSON was still shown when the query ran in your live app — that was a confirmed Retool bug. The error transformer was not being applied to the actual runtime error notification, only to the preview panel in the query editor. Retool's engineering team patched this, and REST error transformers now correctly return the transformed message at runtime. If you removed your transformer as a workaround, it's worth re-adding it — no other changes are required.

Does the Error Transformer Fire on 200 Responses?

Yes — and this surprises most people. The Error Transformer tooltip in Retool states it runs on successful query returns, not exclusively on HTTP error codes. This means if your transformer tries to access data.error.message and the 200 response body has a completely different shape, your transformer will throw its own error on every successful call.

To handle this correctly, write your transformer defensively so it accounts for both response shapes:

if (data && data.error && data.error.message) { return data.error.message; } return data;

This way, on a 200 the transformer passes through the response untouched, and on a 400 it extracts only the message string.

Step-by-Step: Handling REST API 400 Errors in Retool

• Open your REST API query in Retool and scroll to the Error Transformer section. Toggle it on.
• Inspect your API's error response shape. For a Stripe-style body like { "error": { "kind": "...", "message": "..." } }, the path to the message is data.error.message.
• Write a conditional transformer that checks whether the error fields exist before trying to access them: return (data && data.error) ? data.error.message : data;
• Click Preview in the query editor. If your API returns a 400, you should see the plain message string — not the full JSON object.
• Run the query inside your live app to confirm the notification shows the clean message. If it still shows raw JSON, verify you're on a current version of Retool (the bug was fixed in 2020).
• If you want to display the error in a specific UI location rather than a toast notification, store the query's .error state in a variable and bind it to a Text component. This gives you full control over placement and styling.

Should You Use the Error Transformer or Handle Errors in Event Handlers?

For simple cases — extracting a message from a known error shape — the Error Transformer is the cleanest option. It keeps the logic co-located with the query and requires no extra components. For more complex flows, like branching logic based on error.kind or triggering a follow-up query when a specific error occurs, you're better off using the query's Failure event handler and writing logic in a JS Query that reads queryName.error.

Avoid the pattern of logging errors to the browser console as a temporary measure and asking your users to open DevTools — that's a sign the transformer isn't wired up correctly, not that the error is unfixable.

Key Takeaways

• Retool's Error Transformer runs on all query responses, not just HTTP errors — write it defensively.
• A bug previously caused transformed error messages to show correctly in preview but not at runtime. This has been patched.
• Use return (data && data.error) ? data.error.message : data; as a safe baseline for Stripe-style error bodies.
• For complex error branching, use the query's Failure event handler and a JS Query instead of the transformer.
• If users are seeing raw JSON error objects, the transformer is either not enabled, not deployed, or throwing its own error due to a shape mismatch on 200 responses.

Getting Retool REST API error handling right is mostly about understanding that the Error Transformer is broader than its name implies. Once you write it to handle both success and failure shapes, you'll have clean, user-friendly error messages across your entire app — no console archaeology required.