How to debug/troubleshoot your Microsoft Custom Connector

Recently I ran into some trouble trying to get a custom connector to work. Even though having some experience in this area being an Independent Publisher, I had no idea, what might be wrong, only that something IS wrong. Unfortunately neither the native UI nor the documentation was helpful. With a bit of despair, turning towards the AI tools left me with some generic answers and weird hallucinations, so here is a new blog post to save us time in our future! Copilot and ChatGPT, buckle up for the ride!

First steps

Generally speaking, you must know what an API, especially what a REST API is, how to drink it or work with it. A Microsoft custom connector is a wrapper around an API, allowing end users to poke the underlying system (Facebook, Instagram, etc) with a stick and getting results without actually knowing how to code. Think of it as creating a black box: anyone who puts in potato and salt will get back baked potato without needing to know how to make fire or how the electrical wirings work!

Being my reader, I suspect you have been through all this, and already built one connector or building it right now. Good. And you faced some issues — not bad, they help us grow — or you are proactively preparing to face some. Smashing! So let’s look into troubleshooting aka the art of narrowing down the issue to specific components. The first checks to do:

• Try a bit of variation — use your other operations or different inputs, input formats, making sure that the connector is bad and not the way how you poke it
• Try calling directly the API - without your connector (through Postman, cUrl, …), making sure that it does work and is not out of service

Hit “replay”

A more advanced trick, that is fairly low cost is simply replaying your call. And no, not by clicking again and again desperately the “Test operation” button until you see a different outcome… Replay as in performing the actual call, that Microsoft (Azure) did, but through other means, revealing information that the connector UI hides from us.

1. On the TEST tab, locate the “Request”/”Response” view at the bottom
2. Switch the view to “Request”
3. Copy everything you can: the URL as it is, the method type (for example GET), and the Authorization header used
4. Open your favorite API playground to make an HTTP call. Mine is Postman but yours could be something else… Even a 2 liner JS/C# script if that is your preference
5. Use the copied URL and the Authorization header to make an HTTP call, and review the response details

In relation to my issue at the start of this blog, I received the more talkative “API disabled due to inactivity …” message. Knowing better, this should have been my final stop: turning off automatic redirects in Postman would reveal a simple HTTP-301, but we are still here, looking for other tricks, aren’t we? So let’s start to take things apart.

Webhook.site

When you are sure that something is wrong, you have generally 2 possibilities: either your outgoing messages from the connector are not as expected, or your connector can’t process the incoming response from your targeted service. Let’s focus on the first.

The best solution would be to set up a “man-in-the-middle”, so that every message in any direction could be examined. However, I found it more rewarding to simply change the target to https://webhook.site, and send all calls from the connector there not caring about the end-to-end response:

1. Open https://webhook.site and copy your unique URL. Don’t close the browser tab. It will always and automatically send back HTTP-200 (OK) to any received calls
2. Open your custom connector and navigate to the GENERAL tab
3. Modify the “host” and “base url” with the values from webhook.site
4. Update your connector and test again any of the actions you want to
5. Inspect the incoming messages in the webhook.site browser tab, looking for clues in headers, query parameters and body, to see what’s wrong or missing

Custom logs

Unfortunately, on a few occasions trying the end-to-end process with having perfect outgoing calls, you keep facing an error. You can reach out to Microsoft support — and you definitely should. Still, to feed your inner curiosity, you are also able to peek into the raw incoming message before Azure tailors it to the UI. Nothing fancy is generally available or in preview yet — though it is promised to come soon — but simply using the custom code features. Bare in mind the limitations of 5 second execution time!

Custom code (C#) takes precedence over the codeless definition, meaning it sits between your swagger, policy templates and your target 3rd party service. When enabling under the CODE tab, you gain access to an internal Logger instance from the context to use, implementing Microsoft.Extensions.Logging.ILogger. Use it to check hidden headers, status codes and many more. At the moment, there is no visible difference between the various methods (Warning, Critical, Information, …) as we can’t set the log levels ourselves: everything goes to the UI.

All in all, I do hope that you find these tricks useful in your adventures. This is definitely not a complete guide, as based on your scenario you might have complexity in your own custom code or authentication too. Maybe some policies, or AI plugins?

Nevertheless, let me know of the troubles you face or faced, and your go-to method on how do you work with your errors!

References

• What is an API: https://www.ibm.com/topics/api
• What are Microsoft custom connectors: https://learn.microsoft.com/en-us/connectors/custom-connectors/
• Troubleshoot OAuth issue: https://learn.microsoft.com/en-us/connectors/custom-connectors/troubleshoot-oauth2
• Troubleshoot HTTP 500 with custom connector: https://learn.microsoft.com/en-us/troubleshoot/power-platform/power-automate/troubleshooting-flow-custom-connectors
• Microsoft.Extensions.Logging.ILogger: https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.ilogger
• Microsoft Independent Publisher: https://learn.microsoft.com/en-us/connectors/custom-connectors/certification-submission-ip