Asynchronous endpoints

Introduction

To ensure fast response times and high availability, several create operations in the Mambo API are processed asynchronously. These endpoints are designed to accept your request immediately while performing the actual processing in the background, allowing your application to remain responsive even during complex operations.

Asynchronous POST endpoints are marked as async in the API Explorer. When using these endpoints, it's important to understand how they work and how to properly check the status of your requests.

How asynchronous endpoints work

When you send a request to an asynchronous endpoint, the server immediately acknowledges receipt and queues it for processing. This approach prevents long-running operations from blocking your application while ensuring your data is still processed reliably.

Response of asynchronous endpoints

When an asynchronous endpoint receives a POST request, it immediately returns a response with:

• JSON response body containing the id of the entity that will be created asynchronously
• HTTP Status Code 202 Accepted
• Location header containing the URL where you can check the request's processing status

Example response

HTTP

HTTP/1.1 202 Accepted
Location: https://api.mambo.io/v1/status/647b4b40a8e049c9efee5c38
Content-Type: application/json

{
  "id": "647b4b40a8e049c9efee5c38"
}

It's crucial to understand that a 202 Accepted response only indicates that your request was received and queued for processing. It does not guarantee successful processing. For example, a POST request to create a new activity might contain invalid data (like a behaviour verb that doesn't exist). Such a request will be accepted with a 202 Accepted status, but processing might later fail with a ValidationException.

Any response status code other than 202 Accepted indicates that your request was not successful and asynchronous processing will not occur. For example, a POST request to create an activity for a non-existent user will immediately return a 404 UserNotFoundException response.

Checking processing status

To determine if your asynchronous request was processed successfully, you need to check its status using a dedicated endpoint. The URL for this endpoint is provided in the Location header of the original response.

Making a status request

Send a GET request to the URL provided in the Location header:

HTTP

Accept: application/json
GET https://api.mambo.io/v1/status/647b4b40a8e049c9efee5c38

The response will include a status code of 200 and a JSON body with the following fields:

Field name	Value	Description
status	NotProcessed, Processing, Success, Failed	Whether the request still needs to be processed, is being processed, was successful, or failed
exceptionMessage	String escaped JSON Object	If status is FAILED, this field contains the JSON object for the exception encountered
exceptionCode	HTTP status code	If status is FAILED, this field contains the HTTP status code associated with the exception

Example status responses

Request in queue:

HTTP

HTTP/1.1 200 OK
Retry-After: 5
Content-Type: application/json

{
  "status": "NotProcessed"
}

Successful processing:

HTTP

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "Success"
}

Failed processing:

HTTP

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "Failed",
  "exceptionMessage": "{"error":{"type":"KeyNotFoundException","message":"Could not find a behaviour with the ID [676ac53391520fcbcb6b4b20]"}}",
  "exceptionCode": 400
}

The response will also contain a Retry-After header indicating when you can poll again to check the request's status. If you poll more frequently than the recommended interval, your requests might be rejected with a 429 Too Many Requests error.

Best practices for handling asynchronous requests

Implement proper polling with exponential backoff

Rather than polling at fixed intervals, use an exponential backoff strategy that respects the Retry-After header:

JavaScript

function checkStatus(statusUrl, maxAttempts = 10) {
let attempts = 0;

return new Promise((resolve, reject) => {
  const poll = async () => {
    if (attempts >= maxAttempts) {
      reject(new Error('Maximum polling attempts reached'));
      return;
    }
    
    try {
      const response = await fetch(statusUrl);
      const retryAfter = response.headers.get('Retry-After') || 5;
      const data = await response.json();
      
      if (data.status === 'Success') {
        resolve(data);
      } else if (data.status === 'Failed') {
        reject(data);
      } else {
        attempts++;
        setTimeout(poll, retryAfter * 1000);
      }
    } catch (error) {
      reject(error);
    }
  };
  
  poll();
});
}

Store the entity ID immediately

Since the async endpoint returns the entity ID immediately, store it in your application and consider it "pending" until the status endpoint confirms successful processing.

Implement proper error handling

Be prepared to handle all possible status responses, including network errors during polling.

---

Related topics

• Error types
• Activities