Timeouts

Timeouts are an important aspect of API integration that determine how long your application will wait for a response from the Mambo server before aborting the request. Properly configured timeouts help maintain application responsiveness and handle network issues gracefully.

Server timeout limits

The Mambo server times out after 60 seconds. Therefore, it is recommended to set a timeout of at least 60 seconds in any integrations when using the SDKs, especially for operations that involve complex processing or large data sets.

Timeout considerations

There are situations where it can make sense to use a shorter timeout:

• In user-facing interfaces where responsiveness is critical
• For simple data queries that should complete quickly
• During peak usage periods when you need to prioritise user experience
• For non-critical background operations where retry logic is implemented

For critical operations that must complete successfully (like creating activities), use the full 60-second timeout to maximise the chance of completion.

Configuring timeouts

The Mambo SDKs provide two ways to configure timeouts:

1. Global timeout settings - Applied to all requests made by the SDK instance
2. Per-request timeout settings - Configure timeouts for individual requests

Global timeout configuration

When initialising your SDK client, you can set the default timeout that will apply to all requests:

Java

.NET

PHP

Node

// Initialisation with timeout configuration
MamboClient client = MamboClient.builder()
  .credentials( "public_key", "private_key" )
  .readTimeoutMillis( 60000 )      // 60 seconds for read operations
  .connectionTimeoutMillis( 20000 ) // 20 seconds for establishing connection
  .build();

// Initialisation with timeout configuration
ClientConfiguration configuration = new ClientConfiguration()
{
  PublicKey = "public_key",
  PrivateKey = "private_key",
  TimeoutMillis = 60000,         // 60 seconds overall timeout
  ReadWriteTimeoutMillis = 55000  // 55 seconds for read/write operations
};

client = new MamboClient(configuration);

// Initialisation with timeout configuration
$configuration = new ClientConfiguration();
$configuration->setCredentials( 'public_key', 'private_key' );
$configuration->setTimeoutMilliseconds( 60000 );      // 60 seconds overall timeout
$configuration->setConnectTimeoutMilliseconds( 20000 ); // 20 seconds for establishing connection

$client = MamboClient::withConfiguration($configuration);

import { MamboClient } from '@mambo/sdk';

// Initialisation with timeout configuration
const client = new MamboClient({
  clientId: 'public_key',
  clientSecret: 'private_key',
  timeout: 60000 // 60 seconds for the whole request
});

Unlike the other SDKs, the Node SDK applies a single timeout to the whole request rather than separate connection and read timeouts. It defaults to 30 seconds and cannot exceed 5 minutes.

Per-request timeout configuration

For more granular control, you can set timeouts for individual requests using RequestOptions:

Java

.NET

PHP

Node

RequestOptions requestOptions = RequestOptions.builder()
  .readTimeoutMillis( 60000 )      // 60 seconds for read operations
  .connectionTimeoutMillis( 20000 ) // 20 seconds for establishing connection
  .build();

client.activities().createAsync( "acmeinc", data, requestOptions );

RequestOptions requestOptions = new RequestOptions();
requestOptions.TimeoutMillis = 60000,         // 60 seconds overall timeout
requestOptions.ReadWriteTimeoutMillis = 55000  // 55 seconds for read/write operations

client.Activities.createAsync( "acmeinc", data, requestOptions );

$requestOptions = new RequestOptions();
$requestOptions->setTimeoutMilliseconds( 60000 );      // 60 seconds overall timeout
$requestOptions->setConnectTimeoutMilliseconds( 20000 ); // 20 seconds for establishing connection

$client->activities()->createAsync( 'acmeinc', $data, $requestOptions );

const requestOptions = {
  timeout: 60000 // 60 seconds, overriding the timeout configured on the client
};

await client.activities.createAsync('acmeinc', data, requestOptions);

Troubleshooting timeout issues

If you're experiencing timeout errors:

1. Check network conditions - Ensure stable connectivity between your application and the Mambo API
2. Increase timeout values - For complex operations, consider increasing timeout values to the maximum of 60 seconds
3. Implement retry logic - Add appropriate retry mechanisms with backoff for transient failures
4. Review operation complexity - Some operations may require optimisation or breaking down into smaller requests