Troubleshooting Microservices

This page helps you find the cause when a Microservice does not run as you expect.

What is the best way to troubleshoot a Microservice?

Work through these steps in order:

1. Confirm that the trigger event occurred.
2. Confirm that the platform supports the operation type.
3. Check the authentication.
4. Review the payload structure.
5. Examine the middleware logs.
6. Look for retries and timeouts.
7. Validate the permissions.
8. Confirm the environment configuration.

The most useful logs give you:

• HTTP status codes
• request payloads
• response bodies
• correlation IDs
• retry counts

Do not log tokens, credentials, or personal data. Log record IDs and correlation IDs instead.

See Logs for the location of the Microservice logs.

Why do I get a 401 Unauthorized error?

Common causes:

• The API token expired.
• Someone revoked the credentials.
• The auth header is not correct.
• The credentials belong to a different environment.
• The user is no longer active.
• The API permissions changed.

A very common case: an integration runs for months, then it fails. The API token expired, the owner left the company, or someone rotated the credentials and did not update the integration.

Why did my Microservice not run?

Common causes:

• An App Script made the update. An App Script does not trigger a Microservice.
• The operation was a bulk update. A bulk update does not trigger a Microservice.
• The trigger event type was not correct.
• The endpoint or the event has a configuration error.
• A filter condition stopped the run.
• Someone disabled the Microservice.
• The authentication or the permissions failed.

See Event Types for the events that trigger a Microservice.

Why does my Microservice work in production but fail in a sandbox?

Common causes:

• Different credentials
• Missing endpoints
• Different API tokens
• Less compute in the sandbox
• Incomplete test data
• Environment-specific URLs

Why does my Microservice run more than once?

Common causes:

• Several update events on the same record
• Recursive integrations
• Retry behavior
• Several systems that update the same data
• Field updates that occur in stages
• Synchronization loops between platforms

What are the biggest performance risks with Microservices?

Common risks:

• Large payloads
• Recursive event chains
• Too many synchronous calls
• Unbounded retries
• High-frequency polling
• A poor batching strategy
• A trigger on every field update

Best practices:

• Batch work when you can.
• Filter events with care.
• Avoid updates that you do not need.
• Keep the payload small.
• Use asynchronous processing for heavy operations.

See also Best Practices and the FAQ.