Async Operations

All write (modification) operations are asynchronous. When triggered, they return an operation ID that can be used to track progress and results via the /operations/{operationId} endpoint.

Standard async operation response:

{
  "operationId": "op_1234567890abcdef",
  "status": "pending",
  "createdAt": "2025-06-05T12:00:00Z",
  "completedAt": "2025-06-05T12:00:03Z", // null if the operation is still in flight
  "result": null // null if the operation is still in flight
}

Statuses:

• pending: operation is still running
• completed: operation finished successfully
• failed: operation failed; see error field for details

When completed or failed, the /operations/{operationId} endpoint will include additional fields.

On a successful completion, the value of result changes based on the endpoint that started the operation, see each endpoint definition for more details.

{
  "operationId": "op_1234567890abcdef",
  "status": "completed",
  "createdAt": "2025-06-05T12:00:00Z",
  "completedAt": "2025-06-05T12:00:03Z",
  "result": {
    "message": "User added successfully"
  }
}

In case of failure, result contains a standard error model with additional information about the failure.

Since most data validations occurr while handling the initial request, operation error failures are mostly related with advanced gate validations, internal communication failures or other tenant settings.

{
  "operationId": "op_1234567890abcdef",
  "status": "failed",
  "createdAt": "2025-06-05T12:00:00Z",
  "completedAt": "2025-06-05T12:00:01Z",
  "result": {
    "code": "data_access_error", 
    "field": "internal", 
    "reason": "Internal exception, operation could not be completed."
  }
}

Data retention and timeouts:

Completed operations are kept in the system for 30 days.

Each individual operation has a 10 minute timeout, if it doesn't complete in the allocated time, the system will fail it and start a rollback process.