Troubleshoot API Connector Issues

Destination validation fails when saving

Cause: The apiConfigName value does not match an existing Platform API configuration, or Platform cannot be reached.

Resolution: Confirm the API configuration name in Platform exactly matches the value used in the destination payload, and that Platform is reachable from the engine host.

Connection timeouts

Cause: A firewall, proxy, or DNS problem is preventing the engine from reaching the target endpoint, or the endpoint is slow to accept connections.

Resolution: Verify network access from the Detect engine host to the target endpoint. If the endpoint is simply slow, increase Connection Timeout in Millis in the API configuration.

Read (socket) timeouts

Cause: The endpoint accepted the connection but did not send a complete response within the configured read timeout. This can happen on the first request after a bearer token fetch, during load spikes, or when the remote system is overloaded.

Resolution: Increase Read Timeout in Millis if the endpoint is consistently slow, or investigate performance on the remote system.

Certificate or TLS errors

Cause: The target endpoint's certificate is not trusted by the Java truststore used by the Detect engine JVM, or the certificate's hostname does not match the target endpoint URL.

Resolution: Import the endpoint's certificate (or its issuing CA) into the truststore used by the Detect engine, or configure a custom truststore. Confirm the certificate's subject alternative names include the hostname used in Target Endpoint.

401 or 403 errors

Cause: The authorization type, user name and password, or client ID and client secret configured for the API connector are incorrect, expired, or revoked.

Resolution: Verify the authorization type and credentials in the Platform API configuration. For bearer token authentication, confirm the token endpoint is correct and returns a valid access token when called directly.

429 (Too Many Requests) errors

Cause: The downstream API's rate limit has been reached, because the API connector sends events individually rather than in batches.

Resolution: Ask the owner of the downstream API to raise the rate limit, or reduce the event volume sent to that destination.

Messages are not reaching the endpoint, but no error is visible in the destination

Cause: The message may still be queued internally, waiting for the Kafka environment the API connector depends on, or it may have exhausted its retries.

Resolution: Confirm the internal Kafka environment used by the API connector is healthy and reachable. Check whether retries were exhausted for the message; see API Connector Delivery, Retry, and Failure Handling.